code:
.. SPDX-License-Identifier: GPL-2.0

======================
The SGI XFS Filesystem
======================

XFS is a high performance journaling filesystem which originated
on the SGI IRIX platform.  It is completely multi-threaded, can
support large files and large filesystems, extended attributes,
variable block sizes, is extent based, and makes extensive use of
Btrees (directories, extents, free space) to aid both performance
and scalability.

Refer to the documentation at https://xfs.wiki.kernel.org/
for further details.  This implementation is on-disk compatible
with the IRIX version of XFS.

Mount Options
=============

When mounting an XFS filesystem, the following options are accepted.

  allocsize=size
	Sets the buffered I/O end-of-file preallocation size when
	doing delayed allocation writeout (default size is 64KiB).
	Valid values for this option are page size (typically 4KiB)
	through to 1GiB, inclusive, in power-of-2 increments.

	The default behaviour is for dynamic end-of-file
	preallocation size, which uses a set of heuristics to
	optimise the preallocation size based on the current
	allocation patterns within the file and the access patterns
	to the file. Specifying a fixed ``allocsize`` value turns off
	the dynamic behaviour.

  attr2 or noattr2
	The options enable/disable an "opportunistic" improvement to
	be made in the way inline extended attributes are stored
	on-disk.  When the new form is used for the first time when
	``attr2`` is selected (either when setting or removing extended
	attributes) the on-disk superblock feature bit field will be
	updated to reflect this format being in use.

	The default behaviour is determined by the on-disk feature
	bit indicating that ``attr2`` behaviour is active. If either
	mount option is set, then that becomes the new default used
	by the filesystem.

	CRC enabled filesystems always use the ``attr2`` format, and so
	will reject the ``noattr2`` mount option if it is set.

  discard or nodiscard (default)
	Enable/disable the issuing of commands to let the block
	device reclaim space freed by the filesystem.  This is
	useful for SSD devices, thinly provisioned LUNs and virtual
	machine images, but may have a performance impact.

	Note: It is currently recommended that you use the ``fstrim``
	application to ``discard`` unused blocks rather than the ``discard``
	mount option because the performance impact of this option
	is quite severe.

  grpid/bsdgroups or nogrpid/sysvgroups (default)
	These options define what group ID a newly created file
	gets.  When ``grpid`` is set, it takes the group ID of the
	directory in which it is created; otherwise it takes the
	``fsgid`` of the current process, unless the directory has the
	``setgid`` bit set, in which case it takes the ``gid`` from the
	parent directory, and also gets the ``setgid`` bit set if it is
	a directory itself.

  filestreams
	Make the data allocator use the filestreams allocation mode
	across the entire filesystem rather than just on directories
	configured to use it.

  ikeep or noikeep (default)
	When ``ikeep`` is specified, XFS does not delete empty inode
	clusters and keeps them around on disk.  When ``noikeep`` is
	specified, empty inode clusters are returned to the free
	space pool.

  inode32 or inode64 (default)
	When ``inode32`` is specified, it indicates that XFS limits
	inode creation to locations which will not result in inode
	numbers with more than 32 bits of significance.

	When ``inode64`` is specified, it indicates that XFS is allowed
	to create inodes at any location in the filesystem,
	including those which will result in inode numbers occupying
	more than 32 bits of significance.

	``inode32`` is provided for backwards compatibility with older
	systems and applications, since 64 bits inode numbers might
	cause problems for some applications that cannot handle
	large inode numbers.  If applications are in use which do
	not handle inode numbers bigger than 32 bits, the ``inode32``
	option should be specified.

  largeio or nolargeio (default)
	If ``nolargeio`` is specified, the optimal I/O reported in
	``st_blksize`` by **stat(2)** will be as small as possible to allow
	user applications to avoid inefficient read/modify/write
	I/O.  This is typically the page size of the machine, as
	this is the granularity of the page cache.

	If ``largeio`` is specified, a filesystem that was created with a
	``swidth`` specified will return the ``swidth`` value (in bytes)
	in ``st_blksize``. If the filesystem does not have a ``swidth``
	specified but does specify an ``allocsize`` then ``allocsize``
	(in bytes) will be returned instead. Otherwise the behaviour
	is the same as if ``nolargeio`` was specified.

  logbufs=value
	Set the number of in-memory log buffers.  Valid numbers
	range from 2-8 inclusive.

	The default value is 8 buffers.

	If the memory cost of 8 log buffers is too high on small
	systems, then it may be reduced at some cost to performance
	on metadata intensive workloads. The ``logbsize`` option below
	controls the size of each buffer and so is also relevant to
	this case.

  logbsize=value
	Set the size of each in-memory log buffer.  The size may be
	specified in bytes, or in kilobytes with a "k" suffix.
	Valid sizes for version 1 and version 2 logs are 16384 (16k)
	and 32768 (32k).  Valid sizes for version 2 logs also
	include 65536 (64k), 131072 (128k) and 262144 (256k). The
	logbsize must be an integer multiple of the log
	stripe unit configured at **mkfs(8)** time.

	The default value for version 1 logs is 32768, while the
	default value for version 2 logs is MAX(32768, log_sunit).

  logdev=device and rtdev=device
	Use an external log (metadata journal) and/or real-time device.
	An XFS filesystem has up to three parts: a data section, a log
	section, and a real-time section.  The real-time section is
	optional, and the log section can be separate from the data
	section or contained within it.

  noalign
	Data allocations will not be aligned at stripe unit
	boundaries. This is only relevant to filesystems created
	with non-zero data alignment parameters (``sunit``, ``swidth``) by
	**mkfs(8)**.

  norecovery
	The filesystem will be mounted without running log recovery.
	If the filesystem was not cleanly unmounted, it is likely to
	be inconsistent when mounted in ``norecovery`` mode.
	Some files or directories may not be accessible because of this.
	Filesystems mounted ``norecovery`` must be mounted read-only or
	the mount will fail.

  nouuid
	Don't check for double mounted file systems using the file
	system ``uuid``.  This is useful to mount LVM snapshot volumes,
	and often used in combination with ``norecovery`` for mounting
	read-only snapshots.

  noquota
	Forcibly turns off all quota accounting and enforcement
	within the filesystem.

  uquota/usrquota/uqnoenforce/quota
	User disk quota accounting enabled, and limits (optionally)
	enforced.  Refer to **xfs_quota(8)** for further details.

  gquota/grpquota/gqnoenforce
	Group disk quota accounting enabled and limits (optionally)
	enforced.  Refer to **xfs_quota(8)** for further details.

  pquota/prjquota/pqnoenforce
	Project disk quota accounting enabled and limits (optionally)
	enforced.  Refer to **xfs_quota(8)** for further details.

  sunit=value and swidth=value
	Used to specify the stripe unit and width for a RAID device
	or a stripe volume.  "value" must be specified in 512-byte
	block units. These options are only relevant to filesystems
	that were created with non-zero data alignment parameters.

	The ``sunit`` and ``swidth`` parameters specified must be compatible
	with the existing filesystem alignment characteristics.  In
	general, that means the only valid changes to ``sunit`` are
	increasing it by a power-of-2 multiple. Valid ``swidth`` values
	are any integer multiple of a valid ``sunit`` value.

	Typically the only time these mount options are necessary if
	after an underlying RAID device has had it's geometry
	modified, such as adding a new disk to a RAID5 lun and
	reshaping it.

  swalloc
	Data allocations will be rounded up to stripe width boundaries
	when the current end of file is being extended and the file
	size is larger than the stripe width size.

  wsync
	When specified, all filesystem namespace operations are
	executed synchronously. This ensures that when the namespace
	operation (create, unlink, etc) completes, the change to the
	namespace is on stable storage. This is useful in HA setups
	where failover must not result in clients seeing
	inconsistent namespace presentation during or after a
	failover event.

Deprecation of V4 Format
========================

The V4 filesystem format lacks certain features that are supported by
the V5 format, such as metadata checksumming, strengthened metadata
verification, and the ability to store timestamps past the year 2038.
Because of this, the V4 format is deprecated.  All users should upgrade
by backing up their files, reformatting, and restoring from the backup.

Administrators and users can detect a V4 filesystem by running xfs_info
against a filesystem mountpoint and checking for a string containing
"crc=".  If no such string is found, please upgrade xfsprogs to the
latest version and try again.

The deprecation will take place in two parts.  Support for mounting V4
filesystems can now be disabled at kernel build time via Kconfig option.
The option will default to yes until September 2025, at which time it
will be changed to default to no.  In September 2030, support will be
removed from the codebase entirely.

Note: Distributors may choose to withdraw V4 format support earlier than
the dates listed above.

Deprecated Mount Options
========================

===========================     ================
  Name				Removal Schedule
===========================     ================
Mounting with V4 filesystem     September 2030
ikeep/noikeep			September 2025
attr2/noattr2			September 2025
===========================     ================

Removed Mount Options
=====================

===========================     =======
  Name				Removed
===========================	=======
  delaylog/nodelaylog		v4.0
  ihashsize			v4.0
  irixsgid			v4.0
  osyncisdsync/osyncisosync	v4.0
  barrier			v4.19
  nobarrier			v4.19
===========================     =======

sysctls
=======

The following sysctls are available for the XFS filesystem:

  fs.xfs.stats_clear		(Min: 0  Default: 0  Max: 1)
	Setting this to "1" clears accumulated XFS statistics
	in /proc/fs/xfs/stat.  It then immediately resets to "0".

  fs.xfs.xfssyncd_centisecs	(Min: 100  Default: 3000  Max: 720000)
	The interval at which the filesystem flushes metadata
	out to disk and runs internal cache cleanup routines.

  fs.xfs.filestream_centisecs	(Min: 1  Default: 3000  Max: 360000)
	The interval at which the filesystem ages filestreams cache
	references and returns timed-out AGs back to the free stream
	pool.

  fs.xfs.speculative_prealloc_lifetime
	(Units: seconds   Min: 1  Default: 300  Max: 86400)
	The interval at which the background scanning for inodes
	with unused speculative preallocation runs. The scan
	removes unused preallocation from clean inodes and releases
	the unused space back to the free pool.

  fs.xfs.speculative_cow_prealloc_lifetime
	This is an alias for speculative_prealloc_lifetime.

  fs.xfs.error_level		(Min: 0  Default: 3  Max: 11)
	A volume knob for error reporting when internal errors occur.
	This will generate detailed messages & backtraces for filesystem
	shutdowns, for example.  Current threshold values are:

		XFS_ERRLEVEL_OFF:       0
		XFS_ERRLEVEL_LOW:       1
		XFS_ERRLEVEL_HIGH:      5

  fs.xfs.panic_mask		(Min: 0  Default: 0  Max: 256)
	Causes certain error conditions to call BUG(). Value is a bitmask;
	OR together the tags which represent errors which should cause panics:

		XFS_NO_PTAG                     0
		XFS_PTAG_IFLUSH                 0x00000001
		XFS_PTAG_LOGRES                 0x00000002
		XFS_PTAG_AILDELETE              0x00000004
		XFS_PTAG_ERROR_REPORT           0x00000008
		XFS_PTAG_SHUTDOWN_CORRUPT       0x00000010
		XFS_PTAG_SHUTDOWN_IOERROR       0x00000020
		XFS_PTAG_SHUTDOWN_LOGERROR      0x00000040
		XFS_PTAG_FSBLOCK_ZERO           0x00000080
		XFS_PTAG_VERIFIER_ERROR         0x00000100

	This option is intended for debugging only.

  fs.xfs.irix_symlink_mode	(Min: 0  Default: 0  Max: 1)
	Controls whether symlinks are created with mode 0777 (default)
	or whether their mode is affected by the umask (irix mode).

  fs.xfs.irix_sgid_inherit	(Min: 0  Default: 0  Max: 1)
	Controls files created in SGID directories.
	If the group ID of the new file does not match the effective group
	ID or one of the supplementary group IDs of the parent dir, the
	ISGID bit is cleared if the irix_sgid_inherit compatibility sysctl
	is set.

  fs.xfs.inherit_sync		(Min: 0  Default: 1  Max: 1)
	Setting this to "1" will cause the "sync" flag set
	by the **xfs_io(8)** chattr command on a directory to be
	inherited by files in that directory.

  fs.xfs.inherit_nodump		(Min: 0  Default: 1  Max: 1)
	Setting this to "1" will cause the "nodump" flag set
	by the **xfs_io(8)** chattr command on a directory to be
	inherited by files in that directory.

  fs.xfs.inherit_noatime	(Min: 0  Default: 1  Max: 1)
	Setting this to "1" will cause the "noatime" flag set
	by the **xfs_io(8)** chattr command on a directory to be
	inherited by files in that directory.

  fs.xfs.inherit_nosymlinks	(Min: 0  Default: 1  Max: 1)
	Setting this to "1" will cause the "nosymlinks" flag set
	by the **xfs_io(8)** chattr command on a directory to be
	inherited by files in that directory.

  fs.xfs.inherit_nodefrag	(Min: 0  Default: 1  Max: 1)
	Setting this to "1" will cause the "nodefrag" flag set
	by the **xfs_io(8)** chattr command on a directory to be
	inherited by files in that directory.

  fs.xfs.rotorstep		(Min: 1  Default: 1  Max: 256)
	In "inode32" allocation mode, this option determines how many
	files the allocator attempts to allocate in the same allocation
	group before moving to the next allocation group.  The intent
	is to control the rate at which the allocator moves between
	allocation groups when allocating extents for new files.

Deprecated Sysctls
==================

===========================================     ================
  Name                                          Removal Schedule
===========================================     ================
fs.xfs.irix_sgid_inherit                        September 2025
fs.xfs.irix_symlink_mode                        September 2025
fs.xfs.speculative_cow_prealloc_lifetime        September 2025
===========================================     ================

Removed Sysctls
===============

=============================	=======
  Name				Removed
=============================	=======
  fs.xfs.xfsbufd_centisec	v4.0
  fs.xfs.age_buffer_centisecs	v4.0
=============================	=======

Error handling
==============

XFS can act differently according to the type of error found during its
operation. The implementation introduces the following concepts to the error
handler:

 -failure speed:
	Defines how fast XFS should propagate an error upwards when a specific
	error is found during the filesystem operation. It can propagate
	immediately, after a defined number of retries, after a set time period,
	or simply retry forever.

 -error classes:
	Specifies the subsystem the error configuration will apply to, such as
	metadata IO or memory allocation. Different subsystems will have
	different error handlers for which behaviour can be configured.

 -error handlers:
	Defines the behavior for a specific error.

The filesystem behavior during an error can be set via ``sysfs`` files. Each
error handler works independently - the first condition met by an error handler
for a specific class will cause the error to be propagated rather than reset and
retried.

The action taken by the filesystem when the error is propagated is context
dependent - it may cause a shut down in the case of an unrecoverable error,
it may be reported back to userspace, or it may even be ignored because
there's nothing useful we can with the error or anyone we can report it to (e.g.
during unmount).

The configuration files are organized into the following hierarchy for each
mounted filesystem:

  /sys/fs/xfs/<dev>/error/<class>/<error>/

Where:
  <dev>
	The short device name of the mounted filesystem. This is the same device
	name that shows up in XFS kernel error messages as "XFS(<dev>): ..."

  <class>
	The subsystem the error configuration belongs to. As of 4.9, the defined
	classes are:

		- "metadata": applies metadata buffer write IO

  <error>
	The individual error handler configurations.

Each filesystem has "global" error configuration options defined in their top
level directory:

  /sys/fs/xfs/<dev>/error/

  fail_at_unmount		(Min:  0  Default:  1  Max: 1)
	Defines the filesystem error behavior at unmount time.

	If set to a value of 1, XFS will override all other error configurations
	during unmount and replace them with "immediate fail" characteristics.
	i.e. no retries, no retry timeout. This will always allow unmount to
	succeed when there are persistent errors present.

	If set to 0, the configured retry behaviour will continue until all
	retries and/or timeouts have been exhausted. This will delay unmount
	completion when there are persistent errors, and it may prevent the
	filesystem from ever unmounting fully in the case of "retry forever"
	handler configurations.

	Note: there is no guarantee that fail_at_unmount can be set while an
	unmount is in progress. It is possible that the ``sysfs`` entries are
	removed by the unmounting filesystem before a "retry forever" error
	handler configuration causes unmount to hang, and hence the filesystem
	must be configured appropriately before unmount begins to prevent
	unmount hangs.

Each filesystem has specific error class handlers that define the error
propagation behaviour for specific errors. There is also a "default" error
handler defined, which defines the behaviour for all errors that don't have
specific handlers defined. Where multiple retry constraints are configured for
a single error, the first retry configuration that expires will cause the error
to be propagated. The handler configurations are found in the directory:

  /sys/fs/xfs/<dev>/error/<class>/<error>/

  max_retries			(Min: -1  Default: Varies  Max: INTMAX)
	Defines the allowed number of retries of a specific error before
	the filesystem will propagate the error. The retry count for a given
	error context (e.g. a specific metadata buffer) is reset every time
	there is a successful completion of the operation.

	Setting the value to "-1" will cause XFS to retry forever for this
	specific error.

	Setting the value to "0" will cause XFS to fail immediately when the
	specific error is reported.

	Setting the value to "N" (where 0 < N < Max) will make XFS retry the
	operation "N" times before propagating the error.

  retry_timeout_seconds		(Min:  -1  Default:  Varies  Max: 1 day)
	Define the amount of time (in seconds) that the filesystem is
	allowed to retry its operations when the specific error is
	found.

	Setting the value to "-1" will allow XFS to retry forever for this
	specific error.

	Setting the value to "0" will cause XFS to fail immediately when the
	specific error is reported.

	Setting the value to "N" (where 0 < N < Max) will allow XFS to retry the
	operation for up to "N" seconds before propagating the error.

**Note:** The default behaviour for a specific error handler is dependent on both
the class and error context. For example, the default values for
"metadata/ENODEV" are "0" rather than "-1" so that this error handler defaults
to "fail immediately" behaviour. This is done because ENODEV is a fatal,
unrecoverable error no matter how many times the metadata IO is retried.

Workqueue Concurrency
=====================

XFS uses kernel workqueues to parallelize metadata update processes.  This
enables it to take advantage of storage hardware that can service many IO
operations simultaneously.  This interface exposes internal implementation
details of XFS, and as such is explicitly not part of any userspace API/ABI
guarantee the kernel may give userspace.  These are undocumented features of
the generic workqueue implementation XFS uses for concurrency, and they are
provided here purely for diagnostic and tuning purposes and may change at any
time in the future.

The control knobs for a filesystem's workqueues are organized by task at hand
and the short name of the data device.  They all can be found in:

  /sys/bus/workqueue/devices/${task}!${device}

================  ===========
  Task            Description
================  ===========
  xfs_iwalk-$pid  Inode scans of the entire filesystem. Currently limited to
                  mount time quotacheck.
  xfs-gc          Background garbage collection of disk space that have been
                  speculatively allocated beyond EOF or for staging copy on
                  write operations.
================  ===========

For example, the knobs for the quotacheck workqueue for /dev/nvme0n1 would be
found in /sys/bus/workqueue/devices/xfs_iwalk-1111!nvme0n1/.

The interesting knobs for XFS workqueues are as follows:

============     ===========
  Knob           Description
============     ===========
  max_active     Maximum number of background threads that can be started to
                 run the work.
  cpumask        CPUs upon which the threads are allowed to run.
  nice           Relative priority of scheduling the threads.  These are the
                 same nice levels that can be applied to userspace processes.
============     ===========


code:
.. SPDX-License-Identifier: GPL-2.0

Linux kernel for ARC processors
*******************************

Other sources of information
############################

Below are some resources where more information can be found on
ARC processors and relevant open source projects.

- `<https://embarc.org>`_ - Community portal for open source on ARC.
  Good place to start to find relevant FOSS projects, toolchain releases,
  news items and more.

- `<https://github.com/foss-for-synopsys-dwc-arc-processors>`_ -
  Home for all development activities regarding open source projects for
  ARC processors. Some of the projects are forks of various upstream projects,
  where "work in progress" is hosted prior to submission to upstream projects.
  Other projects are developed by Synopsys and made available to community
  as open source for use on ARC Processors.

- `Official Synopsys ARC Processors website
  <https://www.synopsys.com/designware-ip/processor-solutions.html>`_ -
  location, with access to some IP documentation (`Programmer's Reference
  Manual, AKA PRM for ARC HS processors
  <https://www.synopsys.com/dw/doc.php/ds/cc/programmers-reference-manual-ARC-HS.pdf>`_)
  and free versions of some commercial tools (`Free nSIM
  <https://www.synopsys.com/cgi-bin/dwarcnsim/req1.cgi>`_ and
  `MetaWare Light Edition <https://www.synopsys.com/cgi-bin/arcmwtk_lite/reg1.cgi>`_).
  Please note though, registration is required to access both the documentation and
  the tools.

Important note on ARC processors configurability
################################################

ARC processors are highly configurable and several configurable options
are supported in Linux. Some options are transparent to software
(i.e cache geometries, some can be detected at runtime and configured
and used accordingly, while some need to be explicitly selected or configured
in the kernel's configuration utility (AKA "make menuconfig").

However not all configurable options are supported when an ARC processor
is to run Linux. SoC design teams should refer to "Appendix E:
Configuration for ARC Linux" in the ARC HS Databook for configurability
guidelines.

Following these guidelines and selecting valid configuration options
up front is critical to help prevent any unwanted issues during
SoC bringup and software development in general.

Building the Linux kernel for ARC processors
############################################

The process of kernel building for ARC processors is the same as for any other
architecture and could be done in 2 ways:

- Cross-compilation: process of compiling for ARC targets on a development
  host with a different processor architecture (generally x86_64/amd64).
- Native compilation: process of compiling for ARC on a ARC platform
  (hardware board or a simulator like QEMU) with complete development environment
  (GNU toolchain, dtc, make etc) installed on the platform.

In both cases, up-to-date GNU toolchain for ARC for the host is needed.
Synopsys offers prebuilt toolchain releases which can be used for this purpose,
available from:

- Synopsys GNU toolchain releases:
  `<https://github.com/foss-for-synopsys-dwc-arc-processors/toolchain/releases>`_

- Linux kernel compilers collection:
  `<https://mirrors.edge.kernel.org/pub/tools/crosstool>`_

- Bootlin's toolchain collection: `<https://toolchains.bootlin.com>`_

Once the toolchain is installed in the system, make sure its "bin" folder
is added in your ``PATH`` environment variable. Then set ``ARCH=arc`` &
``CROSS_COMPILE=arc-linux`` (or whatever matches installed ARC toolchain prefix)
and then as usual ``make defconfig && make``.

This will produce "vmlinux" file in the root of the kernel source tree
usable for loading on the target system via JTAG.
If you need to get an image usable with U-Boot bootloader,
type ``make uImage`` and ``uImage`` will be produced in ``arch/arc/boot``
folder.

repo_name: angery/linux


code:
.. SPDX-License-Identifier: GPL-2.0

.. kernel-feat:: $srctree/Documentation/features arc


code:
===================
ARC architecture
===================

.. toctree::
    :maxdepth: 1

    arc

    features

.. only::  subproject and html

   Indices
   =======

   * :ref:`genindex`


code:
.. SPDX-License-Identifier: GPL-2.0

CPU Architectures
=================

These books provide programming details about architecture-specific
implementation.

.. toctree::
   :maxdepth: 2

   arc/index
   arm/index
   arm64/index
   ia64/index
   loongarch/index
   m68k/index
   mips/index
   nios2/index
   openrisc/index
   parisc/index
   powerpc/index
   riscv/index
   s390/index
   sh/index
   sparc/index
   x86/index
   xtensa/index


code:
=======================
ARM Linux 2.6 and upper
=======================

    Please check <ftp://ftp.arm.linux.org.uk/pub/armlinux> for
    updates.

Compilation of kernel
---------------------

  In order to compile ARM Linux, you will need a compiler capable of
  generating ARM ELF code with GNU extensions.  GCC 3.3 is known to be
  a good compiler.  Fortunately, you needn't guess.  The kernel will report
  an error if your compiler is a recognized offender.

  To build ARM Linux natively, you shouldn't have to alter the ARCH = line
  in the top level Makefile.  However, if you don't have the ARM Linux ELF
  tools installed as default, then you should change the CROSS_COMPILE
  line as detailed below.

  If you wish to cross-compile, then alter the following lines in the top
  level make file::

    ARCH = <whatever>

  with::

    ARCH = arm

  and::

    CROSS_COMPILE=

  to::

    CROSS_COMPILE=<your-path-to-your-compiler-without-gcc>

  eg.::

    CROSS_COMPILE=arm-linux-

  Do a 'make config', followed by 'make Image' to build the kernel
  (arch/arm/boot/Image).  A compressed image can be built by doing a
  'make zImage' instead of 'make Image'.

Bug reports etc
---------------

  Please send patches to the patch system.  For more information, see
  http://www.arm.linux.org.uk/developer/patches/info.php Always include some
  explanation as to what the patch does and why it is needed.

  Bug reports should be sent to linux-arm-kernel@lists.arm.linux.org.uk,
  or submitted through the web form at
  http://www.arm.linux.org.uk/developer/

  When sending bug reports, please ensure that they contain all relevant
  information, eg. the kernel messages that were printed before/during
  the problem, what you were doing, etc.

Include files
-------------

  Several new include directories have been created under include/asm-arm,
  which are there to reduce the clutter in the top-level directory.  These
  directories, and their purpose is listed below:

  ============= ==========================================================
   `arch-*`	machine/platform specific header files
   `hardware`	driver-internal ARM specific data structures/definitions
   `mach`	descriptions of generic ARM to specific machine interfaces
   `proc-*`	processor dependent header files (currently only two
		categories)
  ============= ==========================================================

Machine/Platform support
------------------------

  The ARM tree contains support for a lot of different machine types.  To
  continue supporting these differences, it has become necessary to split
  machine-specific parts by directory.  For this, the machine category is
  used to select which directories and files get included (we will use
  $(MACHINE) to refer to the category)

  To this end, we now have arch/arm/mach-$(MACHINE) directories which are
  designed to house the non-driver files for a particular machine (eg, PCI,
  memory management, architecture definitions etc).  For all future
  machines, there should be a corresponding arch/arm/mach-$(MACHINE)/include/mach
  directory.

Modules
-------

  Although modularisation is supported (and required for the FP emulator),
  each module on an ARM2/ARM250/ARM3 machine when is loaded will take
  memory up to the next 32k boundary due to the size of the pages.
  Therefore, is modularisation on these machines really worth it?

  However, ARM6 and up machines allow modules to take multiples of 4k, and
  as such Acorn RiscPCs and other architectures using these processors can
  make good use of modularisation.

ADFS Image files
----------------

  You can access image files on your ADFS partitions by mounting the ADFS
  partition, and then using the loopback device driver.  You must have
  losetup installed.

  Please note that the PCEmulator DOS partitions have a partition table at
  the start, and as such, you will have to give '-o offset' to losetup.

Request to developers
---------------------

  When writing device drivers which include a separate assembler file, please
  include it in with the C file, and not the arch/arm/lib directory.  This
  allows the driver to be compiled as a loadable module without requiring
  half the code to be compiled into the kernel image.

  In general, try to avoid using assembler unless it is really necessary.  It
  makes drivers far less easy to port to other hardware.

ST506 hard drives
-----------------

  The ST506 hard drive controllers seem to be working fine (if a little
  slowly).  At the moment they will only work off the controllers on an
  A4x0's motherboard, but for it to work off a Podule just requires
  someone with a podule to add the addresses for the IRQ mask and the
  HDC base to the source.

  As of 31/3/96 it works with two drives (you should get the ADFS
  `*configure` harddrive set to 2). I've got an internal 20MB and a great
  big external 5.25" FH 64MB drive (who could ever want more :-) ).

  I've just got 240K/s off it (a dd with bs=128k); thats about half of what
  RiscOS gets; but it's a heck of a lot better than the 50K/s I was getting
  last week :-)

  Known bug: Drive data errors can cause a hang; including cases where
  the controller has fixed the error using ECC. (Possibly ONLY
  in that case...hmm).

1772 Floppy
-----------
  This also seems to work OK, but hasn't been stressed much lately.  It
  hasn't got any code for disc change detection in there at the moment which
  could be a bit of a problem!  Suggestions on the correct way to do this
  are welcome.

`CONFIG_MACH_` and `CONFIG_ARCH_`
---------------------------------
  A change was made in 2003 to the macro names for new machines.
  Historically, `CONFIG_ARCH_` was used for the bonafide architecture,
  e.g. SA1100, as well as implementations of the architecture,
  e.g. Assabet.  It was decided to change the implementation macros
  to read `CONFIG_MACH_` for clarity.  Moreover, a retroactive fixup has
  not been made because it would complicate patching.

  Previous registrations may be found online.

    <http://www.arm.linux.org.uk/developer/machines/>

Kernel entry (head.S)
---------------------
  The initial entry into the kernel is via head.S, which uses machine
  independent code.  The machine is selected by the value of 'r1' on
  entry, which must be kept unique.

  Due to the large number of machines which the ARM port of Linux provides
  for, we have a method to manage this which ensures that we don't end up
  duplicating large amounts of code.

  We group machine (or platform) support code into machine classes.  A
  class typically based around one or more system on a chip devices, and
  acts as a natural container around the actual implementations.  These
  classes are given directories - arch/arm/mach-<class> - which contain
  the source files and include/mach/ to support the machine class.

  For example, the SA1100 class is based upon the SA1100 and SA1110 SoC
  devices, and contains the code to support the way the on-board and off-
  board devices are used, or the device is setup, and provides that
  machine specific "personality."

  For platforms that support device tree (DT), the machine selection is
  controlled at runtime by passing the device tree blob to the kernel.  At
  compile-time, support for the machine type must be selected.  This allows for
  a single multiplatform kernel build to be used for several machine types.

  For platforms that do not use device tree, this machine selection is
  controlled by the machine type ID, which acts both as a run-time and a
  compile-time code selection method.  You can register a new machine via the
  web site at:

    <http://www.arm.linux.org.uk/developer/machines/>

  Note: Please do not register a machine type for DT-only platforms.  If your
  platform is DT-only, you do not need a registered machine type.

---

Russell King (15/03/2004)


code:
=================
Booting ARM Linux
=================

Author:	Russell King

Date  : 18 May 2002

The following documentation is relevant to 2.4.18-rmk6 and beyond.

In order to boot ARM Linux, you require a boot loader, which is a small
program that runs before the main kernel.  The boot loader is expected
to initialise various devices, and eventually call the Linux kernel,
passing information to the kernel.

Essentially, the boot loader should provide (as a minimum) the
following:

1. Setup and initialise the RAM.
2. Initialise one serial port.
3. Detect the machine type.
4. Setup the kernel tagged list.
5. Load initramfs.
6. Call the kernel image.

1. Setup and initialise RAM
---------------------------

Existing boot loaders:
	MANDATORY
New boot loaders:
	MANDATORY

The boot loader is expected to find and initialise all RAM that the
kernel will use for volatile data storage in the system.  It performs
this in a machine dependent manner.  (It may use internal algorithms
to automatically locate and size all RAM, or it may use knowledge of
the RAM in the machine, or any other method the boot loader designer
sees fit.)

2. Initialise one serial port
-----------------------------

Existing boot loaders:
	OPTIONAL, RECOMMENDED
New boot loaders:
	OPTIONAL, RECOMMENDED

The boot loader should initialise and enable one serial port on the
target.  This allows the kernel serial driver to automatically detect
which serial port it should use for the kernel console (generally
used for debugging purposes, or communication with the target.)

As an alternative, the boot loader can pass the relevant 'console='
option to the kernel via the tagged lists specifying the port, and
serial format options as described in

       Documentation/admin-guide/kernel-parameters.rst.

3. Detect the machine type
--------------------------

Existing boot loaders:
	OPTIONAL
New boot loaders:
	MANDATORY except for DT-only platforms

The boot loader should detect the machine type its running on by some
method.  Whether this is a hard coded value or some algorithm that
looks at the connected hardware is beyond the scope of this document.
The boot loader must ultimately be able to provide a MACH_TYPE_xxx
value to the kernel. (see linux/arch/arm/tools/mach-types).  This
should be passed to the kernel in register r1.

For DT-only platforms, the machine type will be determined by device
tree.  set the machine type to all ones (~0).  This is not strictly
necessary, but assures that it will not match any existing types.

4. Setup boot data
------------------

Existing boot loaders:
	OPTIONAL, HIGHLY RECOMMENDED
New boot loaders:
	MANDATORY

The boot loader must provide either a tagged list or a dtb image for
passing configuration data to the kernel.  The physical address of the
boot data is passed to the kernel in register r2.

4a. Setup the kernel tagged list
--------------------------------

The boot loader must create and initialise the kernel tagged list.
A valid tagged list starts with ATAG_CORE and ends with ATAG_NONE.
The ATAG_CORE tag may or may not be empty.  An empty ATAG_CORE tag
has the size field set to '2' (0x00000002).  The ATAG_NONE must set
the size field to zero.

Any number of tags can be placed in the list.  It is undefined
whether a repeated tag appends to the information carried by the
previous tag, or whether it replaces the information in its
entirety; some tags behave as the former, others the latter.

The boot loader must pass at a minimum the size and location of
the system memory, and root filesystem location.  Therefore, the
minimum tagged list should look::

		+-----------+
  base ->	| ATAG_CORE |  |
		+-----------+  |
		| ATAG_MEM  |  | increasing address
		+-----------+  |
		| ATAG_NONE |  |
		+-----------+  v

The tagged list should be stored in system RAM.

The tagged list must be placed in a region of memory where neither
the kernel decompressor nor initrd 'bootp' program will overwrite
it.  The recommended placement is in the first 16KiB of RAM.

4b. Setup the device tree
-------------------------

The boot loader must load a device tree image (dtb) into system ram
at a 64bit aligned address and initialize it with the boot data.  The
dtb format is documented at https://www.devicetree.org/specifications/.
The kernel will look for the dtb magic value of 0xd00dfeed at the dtb
physical address to determine if a dtb has been passed instead of a
tagged list.

The boot loader must pass at a minimum the size and location of the
system memory, and the root filesystem location.  The dtb must be
placed in a region of memory where the kernel decompressor will not
overwrite it, while remaining within the region which will be covered
by the kernel's low-memory mapping.

A safe location is just above the 128MiB boundary from start of RAM.

5. Load initramfs.
------------------

Existing boot loaders:
	OPTIONAL
New boot loaders:
	OPTIONAL

If an initramfs is in use then, as with the dtb, it must be placed in
a region of memory where the kernel decompressor will not overwrite it
while also with the region which will be covered by the kernel's
low-memory mapping.

A safe location is just above the device tree blob which itself will
be loaded just above the 128MiB boundary from the start of RAM as
recommended above.

6. Calling the kernel image
---------------------------

Existing boot loaders:
	MANDATORY
New boot loaders:
	MANDATORY

There are two options for calling the kernel zImage.  If the zImage
is stored in flash, and is linked correctly to be run from flash,
then it is legal for the boot loader to call the zImage in flash
directly.

The zImage may also be placed in system RAM and called there.  The
kernel should be placed in the first 128MiB of RAM.  It is recommended
that it is loaded above 32MiB in order to avoid the need to relocate
prior to decompression, which will make the boot process slightly
faster.

When booting a raw (non-zImage) kernel the constraints are tighter.
In this case the kernel must be loaded at an offset into system equal
to TEXT_OFFSET - PAGE_OFFSET.

In any case, the following conditions must be met:

- Quiesce all DMA capable devices so that memory does not get
  corrupted by bogus network packets or disk data. This will save
  you many hours of debug.

- CPU register settings

  - r0 = 0,
  - r1 = machine type number discovered in (3) above.
  - r2 = physical address of tagged list in system RAM, or
    physical address of device tree block (dtb) in system RAM

- CPU mode

  All forms of interrupts must be disabled (IRQs and FIQs)

  For CPUs which do not include the ARM virtualization extensions, the
  CPU must be in SVC mode.  (A special exception exists for Angel)

  CPUs which include support for the virtualization extensions can be
  entered in HYP mode in order to enable the kernel to make full use of
  these extensions.  This is the recommended boot method for such CPUs,
  unless the virtualisations are already in use by a pre-installed
  hypervisor.

  If the kernel is not entered in HYP mode for any reason, it must be
  entered in SVC mode.

- Caches, MMUs

  The MMU must be off.

  Instruction cache may be on or off.

  Data cache must be off.

  If the kernel is entered in HYP mode, the above requirements apply to
  the HYP mode configuration in addition to the ordinary PL1 (privileged
  kernel modes) configuration.  In addition, all traps into the
  hypervisor must be disabled, and PL1 access must be granted for all
  peripherals and CPU resources for which this is architecturally
  possible.  Except for entering in HYP mode, the system configuration
  should be such that a kernel which does not include support for the
  virtualization extensions can boot correctly without extra help.

- The boot loader is expected to call the kernel image by jumping
  directly to the first instruction of the kernel image.

  On CPUs supporting the ARM instruction set, the entry must be
  made in ARM state, even for a Thumb-2 kernel.

  On CPUs supporting only the Thumb instruction set such as
  Cortex-M class CPUs, the entry must be made in Thumb state.


code:
=========================================================
Cluster-wide Power-up/power-down race avoidance algorithm
=========================================================

This file documents the algorithm which is used to coordinate CPU and
cluster setup and teardown operations and to manage hardware coherency
controls safely.

The section "Rationale" explains what the algorithm is for and why it is
needed.  "Basic model" explains general concepts using a simplified view
of the system.  The other sections explain the actual details of the
algorithm in use.

Rationale
---------

In a system containing multiple CPUs, it is desirable to have the
ability to turn off individual CPUs when the system is idle, reducing
power consumption and thermal dissipation.

In a system containing multiple clusters of CPUs, it is also desirable
to have the ability to turn off entire clusters.

Turning entire clusters off and on is a risky business, because it
involves performing potentially destructive operations affecting a group
of independently running CPUs, while the OS continues to run.  This
means that we need some coordination in order to ensure that critical
cluster-level operations are only performed when it is truly safe to do
so.

Simple locking may not be sufficient to solve this problem, because
mechanisms like Linux spinlocks may rely on coherency mechanisms which
are not immediately enabled when a cluster powers up.  Since enabling or
disabling those mechanisms may itself be a non-atomic operation (such as
writing some hardware registers and invalidating large caches), other
methods of coordination are required in order to guarantee safe
power-down and power-up at the cluster level.

The mechanism presented in this document describes a coherent memory
based protocol for performing the needed coordination.  It aims to be as
lightweight as possible, while providing the required safety properties.

Basic model
-----------

Each cluster and CPU is assigned a state, as follows:

	- DOWN
	- COMING_UP
	- UP
	- GOING_DOWN

::

	    +---------> UP ----------+
	    |                        v

	COMING_UP                GOING_DOWN

	    ^                        |
	    +--------- DOWN <--------+

DOWN:
	The CPU or cluster is not coherent, and is either powered off or
	suspended, or is ready to be powered off or suspended.

COMING_UP:
	The CPU or cluster has committed to moving to the UP state.
	It may be part way through the process of initialisation and
	enabling coherency.

UP:
	The CPU or cluster is active and coherent at the hardware
	level.  A CPU in this state is not necessarily being used
	actively by the kernel.

GOING_DOWN:
	The CPU or cluster has committed to moving to the DOWN
	state.  It may be part way through the process of teardown and
	coherency exit.

Each CPU has one of these states assigned to it at any point in time.
The CPU states are described in the "CPU state" section, below.

Each cluster is also assigned a state, but it is necessary to split the
state value into two parts (the "cluster" state and "inbound" state) and
to introduce additional states in order to avoid races between different
CPUs in the cluster simultaneously modifying the state.  The cluster-
level states are described in the "Cluster state" section.

To help distinguish the CPU states from cluster states in this
discussion, the state names are given a `CPU_` prefix for the CPU states,
and a `CLUSTER_` or `INBOUND_` prefix for the cluster states.

CPU state
---------

In this algorithm, each individual core in a multi-core processor is
referred to as a "CPU".  CPUs are assumed to be single-threaded:
therefore, a CPU can only be doing one thing at a single point in time.

This means that CPUs fit the basic model closely.

The algorithm defines the following states for each CPU in the system:

	- CPU_DOWN
	- CPU_COMING_UP
	- CPU_UP
	- CPU_GOING_DOWN

::

	 cluster setup and
	CPU setup complete          policy decision
	      +-----------> CPU_UP ------------+
	      |                                v

	CPU_COMING_UP                   CPU_GOING_DOWN

	      ^                                |
	      +----------- CPU_DOWN <----------+
	 policy decision           CPU teardown complete
	or hardware event

The definitions of the four states correspond closely to the states of
the basic model.

Transitions between states occur as follows.

A trigger event (spontaneous) means that the CPU can transition to the
next state as a result of making local progress only, with no
requirement for any external event to happen.

CPU_DOWN:
	A CPU reaches the CPU_DOWN state when it is ready for
	power-down.  On reaching this state, the CPU will typically
	power itself down or suspend itself, via a WFI instruction or a
	firmware call.

	Next state:
		CPU_COMING_UP
	Conditions:
		none

	Trigger events:
		a) an explicit hardware power-up operation, resulting
		   from a policy decision on another CPU;

		b) a hardware event, such as an interrupt.

CPU_COMING_UP:
	A CPU cannot start participating in hardware coherency until the
	cluster is set up and coherent.  If the cluster is not ready,
	then the CPU will wait in the CPU_COMING_UP state until the
	cluster has been set up.

	Next state:
		CPU_UP
	Conditions:
		The CPU's parent cluster must be in CLUSTER_UP.
	Trigger events:
		Transition of the parent cluster to CLUSTER_UP.

	Refer to the "Cluster state" section for a description of the
	CLUSTER_UP state.

CPU_UP:
	When a CPU reaches the CPU_UP state, it is safe for the CPU to
	start participating in local coherency.

	This is done by jumping to the kernel's CPU resume code.

	Note that the definition of this state is slightly different
	from the basic model definition: CPU_UP does not mean that the
	CPU is coherent yet, but it does mean that it is safe to resume
	the kernel.  The kernel handles the rest of the resume
	procedure, so the remaining steps are not visible as part of the
	race avoidance algorithm.

	The CPU remains in this state until an explicit policy decision
	is made to shut down or suspend the CPU.

	Next state:
		CPU_GOING_DOWN
	Conditions:
		none
	Trigger events:
		explicit policy decision

CPU_GOING_DOWN:
	While in this state, the CPU exits coherency, including any
	operations required to achieve this (such as cleaning data
	caches).

	Next state:
		CPU_DOWN
	Conditions:
		local CPU teardown complete
	Trigger events:
		(spontaneous)

Cluster state
-------------

A cluster is a group of connected CPUs with some common resources.
Because a cluster contains multiple CPUs, it can be doing multiple
things at the same time.  This has some implications.  In particular, a
CPU can start up while another CPU is tearing the cluster down.

In this discussion, the "outbound side" is the view of the cluster state
as seen by a CPU tearing the cluster down.  The "inbound side" is the
view of the cluster state as seen by a CPU setting the CPU up.

In order to enable safe coordination in such situations, it is important
that a CPU which is setting up the cluster can advertise its state
independently of the CPU which is tearing down the cluster.  For this
reason, the cluster state is split into two parts:

	"cluster" state: The global state of the cluster; or the state
	on the outbound side:

		- CLUSTER_DOWN
		- CLUSTER_UP
		- CLUSTER_GOING_DOWN

	"inbound" state: The state of the cluster on the inbound side.

		- INBOUND_NOT_COMING_UP
		- INBOUND_COMING_UP

	The different pairings of these states results in six possible
	states for the cluster as a whole::

	                            CLUSTER_UP
	          +==========> INBOUND_NOT_COMING_UP -------------+
	          #                                               |
	                                                          |
	     CLUSTER_UP     <----+                                |
	  INBOUND_COMING_UP      |                                v

	          ^             CLUSTER_GOING_DOWN       CLUSTER_GOING_DOWN
	          #              INBOUND_COMING_UP <=== INBOUND_NOT_COMING_UP

	    CLUSTER_DOWN         |                                |
	  INBOUND_COMING_UP <----+                                |
	                                                          |
	          ^                                               |
	          +===========     CLUSTER_DOWN      <------------+
	                       INBOUND_NOT_COMING_UP

	Transitions -----> can only be made by the outbound CPU, and
	only involve changes to the "cluster" state.

	Transitions ===##> can only be made by the inbound CPU, and only
	involve changes to the "inbound" state, except where there is no
	further transition possible on the outbound side (i.e., the
	outbound CPU has put the cluster into the CLUSTER_DOWN state).

	The race avoidance algorithm does not provide a way to determine
	which exact CPUs within the cluster play these roles.  This must
	be decided in advance by some other means.  Refer to the section
	"Last man and first man selection" for more explanation.

	CLUSTER_DOWN/INBOUND_NOT_COMING_UP is the only state where the
	cluster can actually be powered down.

	The parallelism of the inbound and outbound CPUs is observed by
	the existence of two different paths from CLUSTER_GOING_DOWN/
	INBOUND_NOT_COMING_UP (corresponding to GOING_DOWN in the basic
	model) to CLUSTER_DOWN/INBOUND_COMING_UP (corresponding to
	COMING_UP in the basic model).  The second path avoids cluster
	teardown completely.

	CLUSTER_UP/INBOUND_COMING_UP is equivalent to UP in the basic
	model.  The final transition to CLUSTER_UP/INBOUND_NOT_COMING_UP
	is trivial and merely resets the state machine ready for the
	next cycle.

	Details of the allowable transitions follow.

	The next state in each case is notated

		<cluster state>/<inbound state> (<transitioner>)

	where the <transitioner> is the side on which the transition
	can occur; either the inbound or the outbound side.

CLUSTER_DOWN/INBOUND_NOT_COMING_UP:
	Next state:
		CLUSTER_DOWN/INBOUND_COMING_UP (inbound)
	Conditions:
		none

	Trigger events:
		a) an explicit hardware power-up operation, resulting
		   from a policy decision on another CPU;

		b) a hardware event, such as an interrupt.

CLUSTER_DOWN/INBOUND_COMING_UP:

	In this state, an inbound CPU sets up the cluster, including
	enabling of hardware coherency at the cluster level and any
	other operations (such as cache invalidation) which are required
	in order to achieve this.

	The purpose of this state is to do sufficient cluster-level
	setup to enable other CPUs in the cluster to enter coherency
	safely.

	Next state:
		CLUSTER_UP/INBOUND_COMING_UP (inbound)
	Conditions:
		cluster-level setup and hardware coherency complete
	Trigger events:
		(spontaneous)

CLUSTER_UP/INBOUND_COMING_UP:

	Cluster-level setup is complete and hardware coherency is
	enabled for the cluster.  Other CPUs in the cluster can safely
	enter coherency.

	This is a transient state, leading immediately to
	CLUSTER_UP/INBOUND_NOT_COMING_UP.  All other CPUs on the cluster
	should consider treat these two states as equivalent.

	Next state:
		CLUSTER_UP/INBOUND_NOT_COMING_UP (inbound)
	Conditions:
		none
	Trigger events:
		(spontaneous)

CLUSTER_UP/INBOUND_NOT_COMING_UP:

	Cluster-level setup is complete and hardware coherency is
	enabled for the cluster.  Other CPUs in the cluster can safely
	enter coherency.

	The cluster will remain in this state until a policy decision is
	made to power the cluster down.

	Next state:
		CLUSTER_GOING_DOWN/INBOUND_NOT_COMING_UP (outbound)
	Conditions:
		none
	Trigger events:
		policy decision to power down the cluster

CLUSTER_GOING_DOWN/INBOUND_NOT_COMING_UP:

	An outbound CPU is tearing the cluster down.  The selected CPU
	must wait in this state until all CPUs in the cluster are in the
	CPU_DOWN state.

	When all CPUs are in the CPU_DOWN state, the cluster can be torn
	down, for example by cleaning data caches and exiting
	cluster-level coherency.

	To avoid wasteful unnecessary teardown operations, the outbound
	should check the inbound cluster state for asynchronous
	transitions to INBOUND_COMING_UP.  Alternatively, individual
	CPUs can be checked for entry into CPU_COMING_UP or CPU_UP.

	Next states:

	CLUSTER_DOWN/INBOUND_NOT_COMING_UP (outbound)
		Conditions:
			cluster torn down and ready to power off
		Trigger events:
			(spontaneous)

	CLUSTER_GOING_DOWN/INBOUND_COMING_UP (inbound)
		Conditions:
			none

		Trigger events:
			a) an explicit hardware power-up operation,
			   resulting from a policy decision on another
			   CPU;

			b) a hardware event, such as an interrupt.

CLUSTER_GOING_DOWN/INBOUND_COMING_UP:

	The cluster is (or was) being torn down, but another CPU has
	come online in the meantime and is trying to set up the cluster
	again.

	If the outbound CPU observes this state, it has two choices:

		a) back out of teardown, restoring the cluster to the
		   CLUSTER_UP state;

		b) finish tearing the cluster down and put the cluster
		   in the CLUSTER_DOWN state; the inbound CPU will
		   set up the cluster again from there.

	Choice (a) permits the removal of some latency by avoiding
	unnecessary teardown and setup operations in situations where
	the cluster is not really going to be powered down.

	Next states:

	CLUSTER_UP/INBOUND_COMING_UP (outbound)
		Conditions:
				cluster-level setup and hardware
				coherency complete

		Trigger events:
				(spontaneous)

	CLUSTER_DOWN/INBOUND_COMING_UP (outbound)
		Conditions:
			cluster torn down and ready to power off

		Trigger events:
			(spontaneous)

Last man and First man selection
--------------------------------

The CPU which performs cluster tear-down operations on the outbound side
is commonly referred to as the "last man".

The CPU which performs cluster setup on the inbound side is commonly
referred to as the "first man".

The race avoidance algorithm documented above does not provide a
mechanism to choose which CPUs should play these roles.

Last man:

When shutting down the cluster, all the CPUs involved are initially
executing Linux and hence coherent.  Therefore, ordinary spinlocks can
be used to select a last man safely, before the CPUs become
non-coherent.

First man:

Because CPUs may power up asynchronously in response to external wake-up
events, a dynamic mechanism is needed to make sure that only one CPU
attempts to play the first man role and do the cluster-level
initialisation: any other CPUs must wait for this to complete before
proceeding.

Cluster-level initialisation may involve actions such as configuring
coherency controls in the bus fabric.

The current implementation in mcpm_head.S uses a separate mutual exclusion
mechanism to do this arbitration.  This mechanism is documented in
detail in vlocks.txt.

Features and Limitations
------------------------

Implementation:

	The current ARM-based implementation is split between
	arch/arm/common/mcpm_head.S (low-level inbound CPU operations) and
	arch/arm/common/mcpm_entry.c (everything else):

	__mcpm_cpu_going_down() signals the transition of a CPU to the
	CPU_GOING_DOWN state.

	__mcpm_cpu_down() signals the transition of a CPU to the CPU_DOWN
	state.

	A CPU transitions to CPU_COMING_UP and then to CPU_UP via the
	low-level power-up code in mcpm_head.S.  This could
	involve CPU-specific setup code, but in the current
	implementation it does not.

	__mcpm_outbound_enter_critical() and __mcpm_outbound_leave_critical()
	handle transitions from CLUSTER_UP to CLUSTER_GOING_DOWN
	and from there to CLUSTER_DOWN or back to CLUSTER_UP (in
	the case of an aborted cluster power-down).

	These functions are more complex than the __mcpm_cpu_*()
	functions due to the extra inter-CPU coordination which
	is needed for safe transitions at the cluster level.

	A cluster transitions from CLUSTER_DOWN back to CLUSTER_UP via
	the low-level power-up code in mcpm_head.S.  This
	typically involves platform-specific setup code,
	provided by the platform-specific power_up_setup
	function registered via mcpm_sync_init.

Deep topologies:

	As currently described and implemented, the algorithm does not
	support CPU topologies involving more than two levels (i.e.,
	clusters of clusters are not supported).  The algorithm could be
	extended by replicating the cluster-level states for the
	additional topological levels, and modifying the transition
	rules for the intermediate (non-outermost) cluster levels.

Colophon
--------

Originally created and documented by Dave Martin for Linaro Limited, in
collaboration with Nicolas Pitre and Achin Gupta.

Copyright (C) 2012-2013  Linaro Limited
Distributed under the terms of Version 2 of the GNU General Public
License, as defined in linux/COPYING.


code:
.. SPDX-License-Identifier: GPL-2.0

.. kernel-feat:: $srctree/Documentation/features arm


code:
==========================================================================
Interface for registering and calling firmware-specific operations for ARM
==========================================================================

Written by Tomasz Figa <t.figa@samsung.com>

Some boards are running with secure firmware running in TrustZone secure
world, which changes the way some things have to be initialized. This makes
a need to provide an interface for such platforms to specify available firmware
operations and call them when needed.

Firmware operations can be specified by filling in a struct firmware_ops
with appropriate callbacks and then registering it with register_firmware_ops()
function::

	void register_firmware_ops(const struct firmware_ops *ops)

The ops pointer must be non-NULL. More information about struct firmware_ops
and its members can be found in arch/arm/include/asm/firmware.h header.

There is a default, empty set of operations provided, so there is no need to
set anything if platform does not require firmware operations.

To call a firmware operation, a helper macro is provided::

	#define call_firmware_op(op, ...)				\
		((firmware_ops->op) ? firmware_ops->op(__VA_ARGS__) : (-ENOSYS))

the macro checks if the operation is provided and calls it or otherwise returns
-ENOSYS to signal that given operation is not available (for example, to allow
fallback to legacy operation).

Example of registering firmware operations::

	/* board file */

	static int platformX_do_idle(void)
	{
		/* tell platformX firmware to enter idle */
		return 0;
	}

	static int platformX_cpu_boot(int i)
	{
		/* tell platformX firmware to boot CPU i */
		return 0;
	}

	static const struct firmware_ops platformX_firmware_ops = {
		.do_idle        = exynos_do_idle,
		.cpu_boot       = exynos_cpu_boot,
		/* other operations not available on platformX */
	};

	/* init_early callback of machine descriptor */
	static void __init board_init_early(void)
	{
		register_firmware_ops(&platformX_firmware_ops);
	}

Example of using a firmware operation::

	/* some platform code, e.g. SMP initialization */

	__raw_writel(__pa_symbol(exynos4_secondary_startup),
		CPU1_BOOT_REG);

	/* Call Exynos specific smc call */
	if (call_firmware_op(cpu_boot, cpu) == -ENOSYS)
		cpu_boot_legacy(...); /* Try legacy way */

	gic_raise_softirq(cpumask_of(cpu), 1);


code:
.. SPDX-License-Identifier: GPL-2.0

======================================
Chromebook Boot Flow
======================================

Most recent Chromebooks that use device tree are using the opensource
depthcharge_ bootloader. Depthcharge_ expects the OS to be packaged as a `FIT
Image`_ which contains an OS image as well as a collection of device trees. It
is up to depthcharge_ to pick the right device tree from the `FIT Image`_ and
provide it to the OS.

The scheme that depthcharge_ uses to pick the device tree takes into account
three variables:

- Board name, specified at depthcharge_ compile time. This is $(BOARD) below.
- Board revision number, determined at runtime (perhaps by reading GPIO
  strappings, perhaps via some other method). This is $(REV) below.
- SKU number, read from GPIO strappings at boot time. This is $(SKU) below.

For recent Chromebooks, depthcharge_ creates a match list that looks like this:

- google,$(BOARD)-rev$(REV)-sku$(SKU)
- google,$(BOARD)-rev$(REV)
- google,$(BOARD)-sku$(SKU)
- google,$(BOARD)

Note that some older Chromebooks use a slightly different list that may
not include SKU matching or may prioritize SKU/rev differently.

Note that for some boards there may be extra board-specific logic to inject
extra compatibles into the list, but this is uncommon.

Depthcharge_ will look through all device trees in the `FIT Image`_ trying to
find one that matches the most specific compatible. It will then look
through all device trees in the `FIT Image`_ trying to find the one that
matches the *second most* specific compatible, etc.

When searching for a device tree, depthcharge_ doesn't care where the
compatible string falls within a device tree's root compatible string array.
As an example, if we're on board "lazor", rev 4, SKU 0 and we have two device
trees:

- "google,lazor-rev5-sku0", "google,lazor-rev4-sku0", "qcom,sc7180"
- "google,lazor", "qcom,sc7180"

Then depthcharge_ will pick the first device tree even though
"google,lazor-rev4-sku0" was the second compatible listed in that device tree.
This is because it is a more specific compatible than "google,lazor".

It should be noted that depthcharge_ does not have any smarts to try to
match board or SKU revisions that are "close by". That is to say that
if depthcharge_ knows it's on "rev4" of a board but there is no "rev4"
device tree then depthcharge_ *won't* look for a "rev3" device tree.

In general when any significant changes are made to a board the board
revision number is increased even if none of those changes need to
be reflected in the device tree. Thus it's fairly common to see device
trees with multiple revisions.

It should be noted that, taking into account the above system that
depthcharge_ has, the most flexibility is achieved if the device tree
supporting the newest revision(s) of a board omits the "-rev{REV}"
compatible strings. When this is done then if you get a new board
revision and try to run old software on it then we'll at pick the
newest device tree we know about.

.. _depthcharge: https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/depthcharge/
.. _`FIT Image`: https://doc.coreboot.org/lib/payloads/fit.html


code:
.. SPDX-License-Identifier: GPL-2.0

================
ARM Architecture
================

.. toctree::
   :maxdepth: 1

   arm
   booting
   cluster-pm-race-avoidance
   firmware
   interrupts
   kernel_mode_neon
   kernel_user_helpers
   memory
   mem_alignment
   tcm
   setup
   swp_emulation
   uefi
   vlocks
   porting

   features

SoC-specific documents
======================

.. toctree::
   :maxdepth: 1

   google/chromebook-boot-flow

   ixp4xx

   marvell
   microchip

   netwinder
   nwfpe/index

   keystone/overview
   keystone/knav-qmss

   omap/index

   pxa/mfp

   sa1100/index

   stm32/stm32f746-overview
   stm32/overview
   stm32/stm32h743-overview
   stm32/stm32h750-overview
   stm32/stm32f769-overview
   stm32/stm32f429-overview
   stm32/stm32mp13-overview
   stm32/stm32mp157-overview
   stm32/stm32-dma-mdma-chaining

   sunxi

   samsung/index
   samsung-s3c24xx/index

   sunxi/clocks

   spear/overview

   sti/stih416-overview
   sti/stih407-overview
   sti/stih418-overview
   sti/overview
   sti/stih415-overview

   vfp/release-notes

.. only::  subproject and html

   Indices
   =======

   * :ref:`genindex`


code:
==========
Interrupts
==========

2.5.2-rmk5:
  This is the first kernel that contains a major shake up of some of the
  major architecture-specific subsystems.

Firstly, it contains some pretty major changes to the way we handle the
MMU TLB.  Each MMU TLB variant is now handled completely separately -
we have TLB v3, TLB v4 (without write buffer), TLB v4 (with write buffer),
and finally TLB v4 (with write buffer, with I TLB invalidate entry).
There is more assembly code inside each of these functions, mainly to
allow more flexible TLB handling for the future.

Secondly, the IRQ subsystem.

The 2.5 kernels will be having major changes to the way IRQs are handled.
Unfortunately, this means that machine types that touch the irq_desc[]
array (basically all machine types) will break, and this means every
machine type that we currently have.

Lets take an example.  On the Assabet with Neponset, we have::

                  GPIO25                 IRR:2
        SA1100 ------------> Neponset -----------> SA1111
                                         IIR:1
                                      -----------> USAR
                                         IIR:0
                                      -----------> SMC9196

The way stuff currently works, all SA1111 interrupts are mutually
exclusive of each other - if you're processing one interrupt from the
SA1111 and another comes in, you have to wait for that interrupt to
finish processing before you can service the new interrupt.  Eg, an
IDE PIO-based interrupt on the SA1111 excludes all other SA1111 and
SMC9196 interrupts until it has finished transferring its multi-sector
data, which can be a long time.  Note also that since we loop in the
SA1111 IRQ handler, SA1111 IRQs can hold off SMC9196 IRQs indefinitely.

The new approach brings several new ideas...

We introduce the concept of a "parent" and a "child".  For example,
to the Neponset handler, the "parent" is GPIO25, and the "children"d
are SA1111, SMC9196 and USAR.

We also bring the idea of an IRQ "chip" (mainly to reduce the size of
the irqdesc array).  This doesn't have to be a real "IC"; indeed the
SA11x0 IRQs are handled by two separate "chip" structures, one for
GPIO0-10, and another for all the rest.  It is just a container for
the various operations (maybe this'll change to a better name).
This structure has the following operations::

  struct irqchip {
          /*
           * Acknowledge the IRQ.
           * If this is a level-based IRQ, then it is expected to mask the IRQ
           * as well.
           */
          void (*ack)(unsigned int irq);
          /*
           * Mask the IRQ in hardware.
           */
          void (*mask)(unsigned int irq);
          /*
           * Unmask the IRQ in hardware.
           */
          void (*unmask)(unsigned int irq);
          /*
           * Re-run the IRQ
           */
          void (*rerun)(unsigned int irq);
          /*
           * Set the type of the IRQ.
           */
          int (*type)(unsigned int irq, unsigned int, type);
  };

ack
       - required.  May be the same function as mask for IRQs
         handled by do_level_IRQ.
mask
       - required.
unmask
       - required.
rerun
       - optional.  Not required if you're using do_level_IRQ for all
         IRQs that use this 'irqchip'.  Generally expected to re-trigger
         the hardware IRQ if possible.  If not, may call the handler
	 directly.
type
       - optional.  If you don't support changing the type of an IRQ,
         it should be null so people can detect if they are unable to
         set the IRQ type.

For each IRQ, we keep the following information:

        - "disable" depth (number of disable_irq()s without enable_irq()s)
        - flags indicating what we can do with this IRQ (valid, probe,
          noautounmask) as before
        - status of the IRQ (probing, enable, etc)
        - chip
        - per-IRQ handler
        - irqaction structure list

The handler can be one of the 3 standard handlers - "level", "edge" and
"simple", or your own specific handler if you need to do something special.

The "level" handler is what we currently have - its pretty simple.
"edge" knows about the brokenness of such IRQ implementations - that you
need to leave the hardware IRQ enabled while processing it, and queueing
further IRQ events should the IRQ happen again while processing.  The
"simple" handler is very basic, and does not perform any hardware
manipulation, nor state tracking.  This is useful for things like the
SMC9196 and USAR above.

So, what's changed?
===================

1. Machine implementations must not write to the irqdesc array.

2. New functions to manipulate the irqdesc array.  The first 4 are expected
   to be useful only to machine specific code.  The last is recommended to
   only be used by machine specific code, but may be used in drivers if
   absolutely necessary.

        set_irq_chip(irq,chip)
                Set the mask/unmask methods for handling this IRQ

        set_irq_handler(irq,handler)
                Set the handler for this IRQ (level, edge, simple)

        set_irq_chained_handler(irq,handler)
                Set a "chained" handler for this IRQ - automatically
                enables this IRQ (eg, Neponset and SA1111 handlers).

        set_irq_flags(irq,flags)
                Set the valid/probe/noautoenable flags.

        set_irq_type(irq,type)
                Set active the IRQ edge(s)/level.  This replaces the
                SA1111 INTPOL manipulation, and the set_GPIO_IRQ_edge()
                function.  Type should be one of IRQ_TYPE_xxx defined in
		<linux/irq.h>

3. set_GPIO_IRQ_edge() is obsolete, and should be replaced by set_irq_type.

4. Direct access to SA1111 INTPOL is deprecated.  Use set_irq_type instead.

5. A handler is expected to perform any necessary acknowledgement of the
   parent IRQ via the correct chip specific function.  For instance, if
   the SA1111 is directly connected to a SA1110 GPIO, then you should
   acknowledge the SA1110 IRQ each time you re-read the SA1111 IRQ status.

6. For any child which doesn't have its own IRQ enable/disable controls
   (eg, SMC9196), the handler must mask or acknowledge the parent IRQ
   while the child handler is called, and the child handler should be the
   "simple" handler (not "edge" nor "level").  After the handler completes,
   the parent IRQ should be unmasked, and the status of all children must
   be re-checked for pending events.  (see the Neponset IRQ handler for
   details).

7. fixup_irq() is gone, as is `arch/arm/mach-*/include/mach/irq.h`

Please note that this will not solve all problems - some of them are
hardware based.  Mixing level-based and edge-based IRQs on the same
parent signal (eg neponset) is one such area where a software based
solution can't provide the full answer to low IRQ latency.


code:
===========================================================
Release Notes for Linux on Intel's IXP4xx Network Processor
===========================================================

Maintained by Deepak Saxena <dsaxena@plexity.net>
-------------------------------------------------------------------------

1. Overview

Intel's IXP4xx network processor is a highly integrated SOC that
is targeted for network applications, though it has become popular
in industrial control and other areas due to low cost and power
consumption. The IXP4xx family currently consists of several processors
that support different network offload functions such as encryption,
routing, firewalling, etc. The IXP46x family is an updated version which
supports faster speeds, new memory and flash configurations, and more
integration such as an on-chip I2C controller.

For more information on the various versions of the CPU, see:

   http://developer.intel.com/design/network/products/npfamily/ixp4xx.htm

Intel also made the IXCP1100 CPU for sometime which is an IXP4xx
stripped of much of the network intelligence.

2. Linux Support

Linux currently supports the following features on the IXP4xx chips:

- Dual serial ports
- PCI interface
- Flash access (MTD/JFFS)
- I2C through GPIO on IXP42x
- GPIO for input/output/interrupts
  See arch/arm/mach-ixp4xx/include/mach/platform.h for access functions.
- Timers (watchdog, OS)

The following components of the chips are not supported by Linux and
require the use of Intel's proprietary CSR software:

- USB device interface
- Network interfaces (HSS, Utopia, NPEs, etc)
- Network offload functionality

If you need to use any of the above, you need to download Intel's
software from:

   http://developer.intel.com/design/network/products/npfamily/ixp425.htm

DO NOT POST QUESTIONS TO THE LINUX MAILING LISTS REGARDING THE PROPRIETARY
SOFTWARE.

There are several websites that provide directions/pointers on using
Intel's software:

   - http://sourceforge.net/projects/ixp4xx-osdg/
     Open Source Developer's Guide for using uClinux and the Intel libraries

   - http://gatewaymaker.sourceforge.net/
     Simple one page summary of building a gateway using an IXP425 and Linux

   - http://ixp425.sourceforge.net/
     ATM device driver for IXP425 that relies on Intel's libraries

3. Known Issues/Limitations

3a. Limited inbound PCI window

The IXP4xx family allows for up to 256MB of memory but the PCI interface
can only expose 64MB of that memory to the PCI bus. This means that if
you are running with > 64MB, all PCI buffers outside of the accessible
range will be bounced using the routines in arch/arm/common/dmabounce.c.

3b. Limited outbound PCI window

IXP4xx provides two methods of accessing PCI memory space:

1) A direct mapped window from 0x48000000 to 0x4bffffff (64MB).
   To access PCI via this space, we simply ioremap() the BAR
   into the kernel and we can use the standard read[bwl]/write[bwl]
   macros. This is the preffered method due to speed but it
   limits the system to just 64MB of PCI memory. This can be
   problamatic if using video cards and other memory-heavy devices.

2) If > 64MB of memory space is required, the IXP4xx can be
   configured to use indirect registers to access PCI This allows
   for up to 128MB (0x48000000 to 0x4fffffff) of memory on the bus.
   The disadvantage of this is that every PCI access requires
   three local register accesses plus a spinlock, but in some
   cases the performance hit is acceptable. In addition, you cannot
   mmap() PCI devices in this case due to the indirect nature
   of the PCI window.

By default, the direct method is used for performance reasons. If
you need more PCI memory, enable the IXP4XX_INDIRECT_PCI config option.

3c. GPIO as Interrupts

Currently the code only handles level-sensitive GPIO interrupts

4. Supported platforms

ADI Engineering Coyote Gateway Reference Platform
http://www.adiengineering.com/productsCoyote.html

   The ADI Coyote platform is reference design for those building
   small residential/office gateways. One NPE is connected to a 10/100
   interface, one to 4-port 10/100 switch, and the third to and ADSL
   interface. In addition, it also supports to POTs interfaces connected
   via SLICs. Note that those are not supported by Linux ATM. Finally,
   the platform has two mini-PCI slots used for 802.11[bga] cards.
   Finally, there is an IDE port hanging off the expansion bus.

Gateworks Avila Network Platform
http://www.gateworks.com/support/overview.php

   The Avila platform is basically and IXDP425 with the 4 PCI slots
   replaced with mini-PCI slots and a CF IDE interface hanging off
   the expansion bus.

Intel IXDP425 Development Platform
http://www.intel.com/design/network/products/npfamily/ixdpg425.htm

   This is Intel's standard reference platform for the IXDP425 and is
   also known as the Richfield board. It contains 4 PCI slots, 16MB
   of flash, two 10/100 ports and one ADSL port.

Intel IXDP465 Development Platform
http://www.intel.com/design/network/products/npfamily/ixdp465.htm

   This is basically an IXDP425 with an IXP465 and 32M of flash instead
   of just 16.

Intel IXDPG425 Development Platform

   This is basically and ADI Coyote board with a NEC EHCI controller
   added. One issue with this board is that the mini-PCI slots only
   have the 3.3v line connected, so you can't use a PCI to mini-PCI
   adapter with an E100 card. So to NFS root you need to use either
   the CSR or a WiFi card and a ramdisk that BOOTPs and then does
   a pivot_root to NFS.

Motorola PrPMC1100 Processor Mezanine Card
http://www.fountainsys.com

   The PrPMC1100 is based on the IXCP1100 and is meant to plug into
   and IXP2400/2800 system to act as the system controller. It simply
   contains a CPU and 16MB of flash on the board and needs to be
   plugged into a carrier board to function. Currently Linux only
   supports the Motorola PrPMC carrier board for this platform.

5. TODO LIST

- Add support for Coyote IDE
- Add support for edge-based GPIO interrupts
- Add support for CF IDE on expansion bus

6. Thanks

The IXP4xx work has been funded by Intel Corp. and MontaVista Software, Inc.

The following people have contributed patches/comments/etc:

- Lennerty Buytenhek
- Lutz Jaenicke
- Justin Mayfield
- Robert E. Ranslam

[I know I've forgotten others, please email me to be added]

-------------------------------------------------------------------------

Last Update: 01/04/2005


code:
================
Kernel mode NEON
================

TL;DR summary
-------------
* Use only NEON instructions, or VFP instructions that don't rely on support
  code
* Isolate your NEON code in a separate compilation unit, and compile it with
  '-march=armv7-a -mfpu=neon -mfloat-abi=softfp'
* Put kernel_neon_begin() and kernel_neon_end() calls around the calls into your
  NEON code
* Don't sleep in your NEON code, and be aware that it will be executed with
  preemption disabled

Introduction
------------
It is possible to use NEON instructions (and in some cases, VFP instructions) in
code that runs in kernel mode. However, for performance reasons, the NEON/VFP
register file is not preserved and restored at every context switch or taken
exception like the normal register file is, so some manual intervention is
required. Furthermore, special care is required for code that may sleep [i.e.,
may call schedule()], as NEON or VFP instructions will be executed in a
non-preemptible section for reasons outlined below.

Lazy preserve and restore
-------------------------
The NEON/VFP register file is managed using lazy preserve (on UP systems) and
lazy restore (on both SMP and UP systems). This means that the register file is
kept 'live', and is only preserved and restored when multiple tasks are
contending for the NEON/VFP unit (or, in the SMP case, when a task migrates to
another core). Lazy restore is implemented by disabling the NEON/VFP unit after
every context switch, resulting in a trap when subsequently a NEON/VFP
instruction is issued, allowing the kernel to step in and perform the restore if
necessary.

Any use of the NEON/VFP unit in kernel mode should not interfere with this, so
it is required to do an 'eager' preserve of the NEON/VFP register file, and
enable the NEON/VFP unit explicitly so no exceptions are generated on first
subsequent use. This is handled by the function kernel_neon_begin(), which
should be called before any kernel mode NEON or VFP instructions are issued.
Likewise, the NEON/VFP unit should be disabled again after use to make sure user
mode will hit the lazy restore trap upon next use. This is handled by the
function kernel_neon_end().

Interruptions in kernel mode
----------------------------
For reasons of performance and simplicity, it was decided that there shall be no
preserve/restore mechanism for the kernel mode NEON/VFP register contents. This
implies that interruptions of a kernel mode NEON section can only be allowed if
they are guaranteed not to touch the NEON/VFP registers. For this reason, the
following rules and restrictions apply in the kernel:
* NEON/VFP code is not allowed in interrupt context;
* NEON/VFP code is not allowed to sleep;
* NEON/VFP code is executed with preemption disabled.

If latency is a concern, it is possible to put back to back calls to
kernel_neon_end() and kernel_neon_begin() in places in your code where none of
the NEON registers are live. (Additional calls to kernel_neon_begin() should be
reasonably cheap if no context switch occurred in the meantime)

VFP and support code
--------------------
Earlier versions of VFP (prior to version 3) rely on software support for things
like IEEE-754 compliant underflow handling etc. When the VFP unit needs such
software assistance, it signals the kernel by raising an undefined instruction
exception. The kernel responds by inspecting the VFP control registers and the
current instruction and arguments, and emulates the instruction in software.

Such software assistance is currently not implemented for VFP instructions
executed in kernel mode. If such a condition is encountered, the kernel will
fail and generate an OOPS.

Separating NEON code from ordinary code
---------------------------------------
The compiler is not aware of the special significance of kernel_neon_begin() and
kernel_neon_end(), i.e., that it is only allowed to issue NEON/VFP instructions
between calls to these respective functions. Furthermore, GCC may generate NEON
instructions of its own at -O3 level if -mfpu=neon is selected, and even if the
kernel is currently compiled at -O2, future changes may result in NEON/VFP
instructions appearing in unexpected places if no special care is taken.

Therefore, the recommended and only supported way of using NEON/VFP in the
kernel is by adhering to the following rules:

* isolate the NEON code in a separate compilation unit and compile it with
  '-march=armv7-a -mfpu=neon -mfloat-abi=softfp';
* issue the calls to kernel_neon_begin(), kernel_neon_end() as well as the calls
  into the unit containing the NEON code from a compilation unit which is *not*
  built with the GCC flag '-mfpu=neon' set.

As the kernel is compiled with '-msoft-float', the above will guarantee that
both NEON and VFP instructions will only ever appear in designated compilation
units at any optimization level.

NEON assembler
--------------
NEON assembler is supported with no additional caveats as long as the rules
above are followed.

NEON code generated by GCC
--------------------------
The GCC option -ftree-vectorize (implied by -O3) tries to exploit implicit
parallelism, and generates NEON code from ordinary C source code. This is fully
supported as long as the rules above are followed.

NEON intrinsics
---------------
NEON intrinsics are also supported. However, as code using NEON intrinsics
relies on the GCC header <arm_neon.h>, (which #includes <stdint.h>), you should
observe the following in addition to the rules above:

* Compile the unit containing the NEON intrinsics with '-ffreestanding' so GCC
  uses its builtin version of <stdint.h> (this is a C99 header which the kernel
  does not supply);
* Include <arm_neon.h> last, or at least after <linux/types.h>


code:
============================
Kernel-provided User Helpers
============================

These are segment of kernel provided user code reachable from user space
at a fixed address in kernel memory.  This is used to provide user space
with some operations which require kernel help because of unimplemented
native feature and/or instructions in many ARM CPUs. The idea is for this
code to be executed directly in user mode for best efficiency but which is
too intimate with the kernel counter part to be left to user libraries.
In fact this code might even differ from one CPU to another depending on
the available instruction set, or whether it is a SMP systems. In other
words, the kernel reserves the right to change this code as needed without
warning. Only the entry points and their results as documented here are
guaranteed to be stable.

This is different from (but doesn't preclude) a full blown VDSO
implementation, however a VDSO would prevent some assembly tricks with
constants that allows for efficient branching to those code segments. And
since those code segments only use a few cycles before returning to user
code, the overhead of a VDSO indirect far call would add a measurable
overhead to such minimalistic operations.

User space is expected to bypass those helpers and implement those things
inline (either in the code emitted directly by the compiler, or part of
the implementation of a library call) when optimizing for a recent enough
processor that has the necessary native support, but only if resulting
binaries are already to be incompatible with earlier ARM processors due to
usage of similar native instructions for other things.  In other words
don't make binaries unable to run on earlier processors just for the sake
of not using these kernel helpers if your compiled code is not going to
use new instructions for other purpose.

New helpers may be added over time, so an older kernel may be missing some
helpers present in a newer kernel.  For this reason, programs must check
the value of __kuser_helper_version (see below) before assuming that it is
safe to call any particular helper.  This check should ideally be
performed only once at process startup time, and execution aborted early
if the required helpers are not provided by the kernel version that
process is running on.

kuser_helper_version
--------------------

Location:	0xffff0ffc

Reference declaration::

  extern int32_t __kuser_helper_version;

Definition:

  This field contains the number of helpers being implemented by the
  running kernel.  User space may read this to determine the availability
  of a particular helper.

Usage example::

  #define __kuser_helper_version (*(int32_t *)0xffff0ffc)

  void check_kuser_version(void)
  {
	if (__kuser_helper_version < 2) {
		fprintf(stderr, "can't do atomic operations, kernel too old\n");
		abort();
	}
  }

Notes:

  User space may assume that the value of this field never changes
  during the lifetime of any single process.  This means that this
  field can be read once during the initialisation of a library or
  startup phase of a program.

kuser_get_tls
-------------

Location:	0xffff0fe0

Reference prototype::

  void * __kuser_get_tls(void);

Input:

  lr = return address

Output:

  r0 = TLS value

Clobbered registers:

  none

Definition:

  Get the TLS value as previously set via the __ARM_NR_set_tls syscall.

Usage example::

  typedef void * (__kuser_get_tls_t)(void);
  #define __kuser_get_tls (*(__kuser_get_tls_t *)0xffff0fe0)

  void foo()
  {
	void *tls = __kuser_get_tls();
	printf("TLS = %p\n", tls);
  }

Notes:

  - Valid only if __kuser_helper_version >= 1 (from kernel version 2.6.12).

kuser_cmpxchg
-------------

Location:	0xffff0fc0

Reference prototype::

  int __kuser_cmpxchg(int32_t oldval, int32_t newval, volatile int32_t *ptr);

Input:

  r0 = oldval
  r1 = newval
  r2 = ptr
  lr = return address

Output:

  r0 = success code (zero or non-zero)
  C flag = set if r0 == 0, clear if r0 != 0

Clobbered registers:

  r3, ip, flags

Definition:

  Atomically store newval in `*ptr` only if `*ptr` is equal to oldval.
  Return zero if `*ptr` was changed or non-zero if no exchange happened.
  The C flag is also set if `*ptr` was changed to allow for assembly
  optimization in the calling code.

Usage example::

  typedef int (__kuser_cmpxchg_t)(int oldval, int newval, volatile int *ptr);
  #define __kuser_cmpxchg (*(__kuser_cmpxchg_t *)0xffff0fc0)

  int atomic_add(volatile int *ptr, int val)
  {
	int old, new;

	do {
		old = *ptr;
		new = old + val;
	} while(__kuser_cmpxchg(old, new, ptr));

	return new;
  }

Notes:

  - This routine already includes memory barriers as needed.

  - Valid only if __kuser_helper_version >= 2 (from kernel version 2.6.12).

kuser_memory_barrier
--------------------

Location:	0xffff0fa0

Reference prototype::

  void __kuser_memory_barrier(void);

Input:

  lr = return address

Output:

  none

Clobbered registers:

  none

Definition:

  Apply any needed memory barrier to preserve consistency with data modified
  manually and __kuser_cmpxchg usage.

Usage example::

  typedef void (__kuser_dmb_t)(void);
  #define __kuser_dmb (*(__kuser_dmb_t *)0xffff0fa0)

Notes:

  - Valid only if __kuser_helper_version >= 3 (from kernel version 2.6.15).

kuser_cmpxchg64
---------------

Location:	0xffff0f60

Reference prototype::

  int __kuser_cmpxchg64(const int64_t *oldval,
                        const int64_t *newval,
                        volatile int64_t *ptr);

Input:

  r0 = pointer to oldval
  r1 = pointer to newval
  r2 = pointer to target value
  lr = return address

Output:

  r0 = success code (zero or non-zero)
  C flag = set if r0 == 0, clear if r0 != 0

Clobbered registers:

  r3, lr, flags

Definition:

  Atomically store the 64-bit value pointed by `*newval` in `*ptr` only if `*ptr`
  is equal to the 64-bit value pointed by `*oldval`.  Return zero if `*ptr` was
  changed or non-zero if no exchange happened.

  The C flag is also set if `*ptr` was changed to allow for assembly
  optimization in the calling code.

Usage example::

  typedef int (__kuser_cmpxchg64_t)(const int64_t *oldval,
                                    const int64_t *newval,
                                    volatile int64_t *ptr);
  #define __kuser_cmpxchg64 (*(__kuser_cmpxchg64_t *)0xffff0f60)

  int64_t atomic_add64(volatile int64_t *ptr, int64_t val)
  {
	int64_t old, new;

	do {
		old = *ptr;
		new = old + val;
	} while(__kuser_cmpxchg64(&old, &new, ptr));

	return new;
  }

Notes:

  - This routine already includes memory barriers as needed.

  - Due to the length of this sequence, this spans 2 conventional kuser
    "slots", therefore 0xffff0f80 is not used as a valid entry point.

  - Valid only if __kuser_helper_version >= 5 (from kernel version 3.1).


code:
======================================================================
Texas Instruments Keystone Navigator Queue Management SubSystem driver
======================================================================

Driver source code path
  drivers/soc/ti/knav_qmss.c
  drivers/soc/ti/knav_qmss_acc.c

The QMSS (Queue Manager Sub System) found on Keystone SOCs is one of
the main hardware sub system which forms the backbone of the Keystone
multi-core Navigator. QMSS consist of queue managers, packed-data structure
processors(PDSP), linking RAM, descriptor pools and infrastructure
Packet DMA.
The Queue Manager is a hardware module that is responsible for accelerating
management of the packet queues. Packets are queued/de-queued by writing or
reading descriptor address to a particular memory mapped location. The PDSPs
perform QMSS related functions like accumulation, QoS, or event management.
Linking RAM registers are used to link the descriptors which are stored in
descriptor RAM. Descriptor RAM is configurable as internal or external memory.
The QMSS driver manages the PDSP setups, linking RAM regions,
queue pool management (allocation, push, pop and notify) and descriptor
pool management.

knav qmss driver provides a set of APIs to drivers to open/close qmss queues,
allocate descriptor pools, map the descriptors, push/pop to queues etc. For
details of the available APIs, please refers to include/linux/soc/ti/knav_qmss.h

DT documentation is available at
Documentation/devicetree/bindings/soc/ti/keystone-navigator-qmss.txt

Accumulator QMSS queues using PDSP firmware
============================================
The QMSS PDSP firmware support accumulator channel that can monitor a single
queue or multiple contiguous queues. drivers/soc/ti/knav_qmss_acc.c is the
driver that interface with the accumulator PDSP. This configures
accumulator channels defined in DTS (example in DT documentation) to monitor
1 or 32 queues per channel. More description on the firmware is available in
CPPI/QMSS Low Level Driver document (docs/CPPI_QMSS_LLD_SDS.pdf) at

	git://git.ti.com/keystone-rtos/qmss-lld.git

k2_qmss_pdsp_acc48_k2_le_1_0_0_9.bin firmware supports upto 48 accumulator
channels. This firmware is available under ti-keystone folder of
firmware.git at

   git://git.kernel.org/pub/scm/linux/kernel/git/firmware/linux-firmware.git

To use copy the firmware image to lib/firmware folder of the initramfs or
ubifs file system and provide a sym link to k2_qmss_pdsp_acc48_k2_le_1_0_0_9.bin
in the file system and boot up the kernel. User would see

 "firmware file ks2_qmss_pdsp_acc48.bin downloaded for PDSP"

in the boot up log if loading of firmware to PDSP is successful.

Use of accumulated queues requires the firmware image to be present in the
file system. The driver doesn't acc queues to the supported queue range if
PDSP is not running in the SoC. The API call fails if there is a queue open
request to an acc queue and PDSP is not running. So make sure to copy firmware
to file system before using these queue types.


code:
==========================
TI Keystone Linux Overview
==========================

Introduction
------------
Keystone range of SoCs are based on ARM Cortex-A15 MPCore Processors
and c66x DSP cores. This document describes essential information required
for users to run Linux on Keystone based EVMs from Texas Instruments.

Following SoCs  & EVMs are currently supported:-

K2HK SoC and EVM
=================

a.k.a Keystone 2 Hawking/Kepler SoC
TCI6636K2H & TCI6636K2K: See documentation at

	http://www.ti.com/product/tci6638k2k
	http://www.ti.com/product/tci6638k2h

EVM:
  http://www.advantech.com/Support/TI-EVM/EVMK2HX_sd.aspx

K2E SoC and EVM
===============

a.k.a Keystone 2 Edison SoC

K2E  -  66AK2E05:

See documentation at

	http://www.ti.com/product/66AK2E05/technicaldocuments

EVM:
   https://www.einfochips.com/index.php/partnerships/texas-instruments/k2e-evm.html

K2L SoC and EVM
===============

a.k.a Keystone 2 Lamarr SoC

K2L  -  TCI6630K2L:

See documentation at
	http://www.ti.com/product/TCI6630K2L/technicaldocuments

EVM:
  https://www.einfochips.com/index.php/partnerships/texas-instruments/k2l-evm.html

Configuration
-------------

All of the K2 SoCs/EVMs share a common defconfig, keystone_defconfig and same
image is used to boot on individual EVMs. The platform configuration is
specified through DTS. Following are the DTS used:

	K2HK EVM:
		k2hk-evm.dts
	K2E EVM:
		k2e-evm.dts
	K2L EVM:
		k2l-evm.dts

The device tree documentation for the keystone machines are located at

        Documentation/devicetree/bindings/arm/keystone/keystone.txt

Document Author
---------------
Murali Karicheri <m-karicheri2@ti.com>

Copyright 2015 Texas Instruments