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

====================
Intel StrongARM 1100
====================

.. toctree::
    :maxdepth: 1

    assabet
    cerf
    lart
    serial_uart


code:
====================================
Linux Advanced Radio Terminal (LART)
====================================

The LART is a small (7.5 x 10cm) SA-1100 board, designed for embedded
applications. It has 32 MB DRAM, 4MB Flash ROM, double RS232 and all
other StrongARM-gadgets. Almost all SA signals are directly accessible
through a number of connectors. The powersupply accepts voltages
between 3.5V and 16V and is overdimensioned to support a range of
daughterboards. A quad Ethernet / IDE / PS2 / sound daughterboard
is under development, with plenty of others in different stages of
planning.

The hardware designs for this board have been released under an open license;
see the LART page at http://www.lartmaker.nl/ for more information.

repo_name: angery/linux


code:
==================
SA1100 serial port
==================

The SA1100 serial port had its major/minor numbers officially assigned::

  > Date: Sun, 24 Sep 2000 21:40:27 -0700
  > From: H. Peter Anvin <hpa@transmeta.com>
  > To: Nicolas Pitre <nico@CAM.ORG>
  > Cc: Device List Maintainer <device@lanana.org>
  > Subject: Re: device
  >
  > Okay.  Note that device numbers 204 and 205 are used for "low density
  > serial devices", so you will have a range of minors on those majors (the
  > tty device layer handles this just fine, so you don't have to worry about
  > doing anything special.)
  >
  > So your assignments are:
  >
  > 204 char        Low-density serial ports
  >                   5 = /dev/ttySA0               SA1100 builtin serial port 0
  >                   6 = /dev/ttySA1               SA1100 builtin serial port 1
  >                   7 = /dev/ttySA2               SA1100 builtin serial port 2
  >
  > 205 char        Low-density serial ports (alternate device)
  >                   5 = /dev/cusa0                Callout device for ttySA0
  >                   6 = /dev/cusa1                Callout device for ttySA1
  >                   7 = /dev/cusa2                Callout device for ttySA2
  >

You must create those inodes in /dev on the root filesystem used
by your SA1100-based device::

	mknod ttySA0 c 204 5
	mknod ttySA1 c 204 6
	mknod ttySA2 c 204 7
	mknod cusa0 c 205 5
	mknod cusa1 c 205 6
	mknod cusa2 c 205 7

In addition to the creation of the appropriate device nodes above, you
must ensure your user space applications make use of the correct device
name. The classic example is the content of the /etc/inittab file where
you might have a getty process started on ttyS0.

In this case:

- replace occurrences of ttyS0 with ttySA0, ttyS1 with ttySA1, etc.

- don't forget to add 'ttySA0', 'console', or the appropriate tty name
  in /etc/securetty for root to be allowed to login as well.


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

=======================
S3C24XX CPUfreq support
=======================

Introduction
------------

 The S3C24XX series support a number of power saving systems, such as
 the ability to change the core, memory and peripheral operating
 frequencies. The core control is exported via the CPUFreq driver
 which has a number of different manual or automatic controls over the
 rate the core is running at.

 There are two forms of the driver depending on the specific CPU and
 how the clocks are arranged. The first implementation used as single
 PLL to feed the ARM, memory and peripherals via a series of dividers
 and muxes and this is the implementation that is documented here. A
 newer version where there is a separate PLL and clock divider for the
 ARM core is available as a separate driver.

Layout
------

 The code core manages the CPU specific drivers, any data that they
 need to register and the interface to the generic drivers/cpufreq
 system. Each CPU registers a driver to control the PLL, clock dividers
 and anything else associated with it. Any board that wants to use this
 framework needs to supply at least basic details of what is required.

 The core registers with drivers/cpufreq at init time if all the data
 necessary has been supplied.

CPU support
-----------

 The support for each CPU depends on the facilities provided by the
 SoC and the driver as each device has different PLL and clock chains
 associated with it.

Slow Mode
---------

 The SLOW mode where the PLL is turned off altogether and the
 system is fed by the external crystal input is currently not
 supported.

sysfs
-----

 The core code exports extra information via sysfs in the directory
 devices/system/cpu/cpu0/arch-freq.

Board Support
-------------

 Each board that wants to use the cpufreq code must register some basic
 information with the core driver to provide information about what the
 board requires and any restrictions being placed on it.

 The board needs to supply information about whether it needs the IO bank
 timings changing, any maximum frequency limits and information about the
 SDRAM refresh rate.

Document Author
---------------

Ben Dooks, Copyright 2009 Simtec Electronics


code:
===================================
Simtec Electronics EB2410ITX (BAST)
===================================

	http://www.simtec.co.uk/products/EB2410ITX/

Introduction
------------

  The EB2410ITX is a S3C2410 based development board with a variety of
  peripherals and expansion connectors. This board is also known by
  the shortened name of Bast.

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

  To set the default configuration, use `make bast_defconfig` which
  supports the commonly used features of this board.

Support
-------

  Official support information can be found on the Simtec Electronics
  website, at the product page http://www.simtec.co.uk/products/EB2410ITX/

  Useful links:

    - Resources Page http://www.simtec.co.uk/products/EB2410ITX/resources.html

    - Board FAQ at http://www.simtec.co.uk/products/EB2410ITX/faq.html

    - Bootloader info http://www.simtec.co.uk/products/SWABLE/resources.html
      and FAQ http://www.simtec.co.uk/products/SWABLE/faq.html

MTD
---

  The NAND and NOR support has been merged from the linux-mtd project.
  Any problems, see http://www.linux-mtd.infradead.org/ for more
  information or up-to-date versions of linux-mtd.

IDE
---

  Both onboard IDE ports are supported, however there is no support for
  changing speed of devices, PIO Mode 4 capable drives should be used.

Maintainers
-----------

  This board is maintained by Simtec Electronics.

Copyright 2004 Ben Dooks, Simtec Electronics


code:
====================
S3C24XX GPIO Control
====================

Introduction
------------

  The s3c2410 kernel provides an interface to configure and
  manipulate the state of the GPIO pins, and find out other
  information about them.

  There are a number of conditions attached to the configuration
  of the s3c2410 GPIO system, please read the Samsung provided
  data-sheet/users manual to find out the complete list.

  See Documentation/arm/samsung/gpio.rst for the core implementation.

GPIOLIB
-------

  With the event of the GPIOLIB in drivers/gpio, support for some
  of the GPIO functions such as reading and writing a pin will
  be removed in favour of this common access method.

  Once all the extant drivers have been converted, the functions
  listed below will be removed (they may be marked as __deprecated
  in the near future).

  The following functions now either have a `s3c_` specific variant
  or are merged into gpiolib. See the definitions in
  arch/arm/mach-s3c/gpio-cfg.h:

  - s3c2410_gpio_setpin()	gpio_set_value() or gpio_direction_output()
  - s3c2410_gpio_getpin()	gpio_get_value() or gpio_direction_input()
  - s3c2410_gpio_getirq()	gpio_to_irq()
  - s3c2410_gpio_cfgpin()	s3c_gpio_cfgpin()
  - s3c2410_gpio_getcfg()	s3c_gpio_getcfg()
  - s3c2410_gpio_pullup()	s3c_gpio_setpull()

GPIOLIB conversion
------------------

If you need to convert your board or driver to use gpiolib from the phased
out s3c2410 API, then here are some notes on the process.

1) If your board is exclusively using an GPIO, say to control peripheral
   power, then it will require to claim the gpio with gpio_request() before
   it can use it.

   It is recommended to check the return value, with at least WARN_ON()
   during initialisation.

2) The s3c2410_gpio_cfgpin() can be directly replaced with s3c_gpio_cfgpin()
   as they have the same arguments, and can either take the pin specific
   values, or the more generic special-function-number arguments.

3) s3c2410_gpio_pullup() changes have the problem that while the
   s3c2410_gpio_pullup(x, 1) can be easily translated to the
   s3c_gpio_setpull(x, S3C_GPIO_PULL_NONE), the s3c2410_gpio_pullup(x, 0)
   are not so easy.

   The s3c2410_gpio_pullup(x, 0) case enables the pull-up (or in the case
   of some of the devices, a pull-down) and as such the new API distinguishes
   between the UP and DOWN case. There is currently no 'just turn on' setting
   which may be required if this becomes a problem.

4) s3c2410_gpio_setpin() can be replaced by gpio_set_value(), the old call
   does not implicitly configure the relevant gpio to output. The gpio
   direction should be changed before using gpio_set_value().

5) s3c2410_gpio_getpin() is replaceable by gpio_get_value() if the pin
   has been set to input. It is currently unknown what the behaviour is
   when using gpio_get_value() on an output pin (s3c2410_gpio_getpin
   would return the value the pin is supposed to be outputting).

6) s3c2410_gpio_getirq() should be directly replaceable with the
   gpio_to_irq() call.

The s3c2410_gpio and `gpio_` calls have always operated on the same gpio
numberspace, so there is no problem with converting the gpio numbering
between the calls.

Headers
-------

  See arch/arm/mach-s3c/regs-gpio-s3c24xx.h for the list
  of GPIO pins, and the configuration values for them. This
  is included by using #include <mach/regs-gpio.h>

PIN Numbers
-----------

  Each pin has an unique number associated with it in regs-gpio.h,
  e.g. S3C2410_GPA(0) or S3C2410_GPF(1). These defines are used to tell
  the GPIO functions which pin is to be used.

  With the conversion to gpiolib, there is no longer a direct conversion
  from gpio pin number to register base address as in earlier kernels. This
  is due to the number space required for newer SoCs where the later
  GPIOs are not contiguous.

Configuring a pin
-----------------

  The following function allows the configuration of a given pin to
  be changed.

    void s3c_gpio_cfgpin(unsigned int pin, unsigned int function);

  e.g.:

     s3c_gpio_cfgpin(S3C2410_GPA(0), S3C_GPIO_SFN(1));
     s3c_gpio_cfgpin(S3C2410_GPE(8), S3C_GPIO_SFN(2));

   which would turn GPA(0) into the lowest Address line A0, and set
   GPE(8) to be connected to the SDIO/MMC controller's SDDAT1 line.

Reading the current configuration
---------------------------------

  The current configuration of a pin can be read by using standard
  gpiolib function:

  s3c_gpio_getcfg(unsigned int pin);

  The return value will be from the same set of values which can be
  passed to s3c_gpio_cfgpin().

Configuring a pull-up resistor
------------------------------

  A large proportion of the GPIO pins on the S3C2410 can have weak
  pull-up resistors enabled. This can be configured by the following
  function:

    void s3c_gpio_setpull(unsigned int pin, unsigned int to);

  Where the to value is S3C_GPIO_PULL_NONE to set the pull-up off,
  and S3C_GPIO_PULL_UP to enable the specified pull-up. Any other
  values are currently undefined.

Getting and setting the state of a PIN
--------------------------------------

  These calls are now implemented by the relevant gpiolib calls, convert
  your board or driver to use gpiolib.

Getting the IRQ number associated with a PIN
--------------------------------------------

  A standard gpiolib function can map the given pin number to an IRQ
  number to pass to the IRQ system.

   int gpio_to_irq(unsigned int pin);

  Note, not all pins have an IRQ.

Author
-------

Ben Dooks, 03 October 2004
Copyright 2004 Ben Dooks, Simtec Electronics


code:
=============
HP IPAQ H1940
=============

http://www.handhelds.org/projects/h1940.html

Introduction
------------

  The HP H1940 is a S3C2410 based handheld device, with
  bluetooth connectivity.

Support
-------

  A variety of information is available

  handhelds.org project page:

    http://www.handhelds.org/projects/h1940.html

  handhelds.org wiki page:

    http://handhelds.org/moin/moin.cgi/HpIpaqH1940

  Herbert Pötzl pages:

    http://vserver.13thfloor.at/H1940/

Maintainers
-----------

  This project is being maintained and developed by a variety
  of people, including Ben Dooks, Arnaud Patard, and Herbert Pötzl.

  Thanks to the many others who have also provided support.

(c) 2005 Ben Dooks


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

==========================
Samsung S3C24XX SoC Family
==========================

.. toctree::
   :maxdepth: 1

   h1940
   gpio
   cpufreq
   suspend
   usb-host
   s3c2412
   eb2410itx
   nand
   smdk2440
   s3c2413
   overview


code:
====================
S3C24XX NAND Support
====================

Introduction
------------

Small Page NAND
---------------

The driver uses a 512 byte (1 page) ECC code for this setup. The
ECC code is not directly compatible with the default kernel ECC
code, so the driver enforces its own OOB layout and ECC parameters

Large Page NAND
---------------

The driver is capable of handling NAND flash with a 2KiB page
size, with support for hardware ECC generation and correction.

Unlike the 512byte page mode, the driver generates ECC data for
each 256 byte block in an 2KiB page. This means that more than
one error in a page can be rectified. It also means that the
OOB layout remains the default kernel layout for these flashes.

Document Author
---------------

Ben Dooks, Copyright 2007 Simtec Electronics


code:
==========================
S3C24XX ARM Linux Overview
==========================

Introduction
------------

  The Samsung S3C24XX range of ARM9 System-on-Chip CPUs are supported
  by the 's3c2410' architecture of ARM Linux. Currently the S3C2410,
  S3C2412, S3C2413, S3C2416, S3C2440, S3C2442, S3C2443 and S3C2450 devices
  are supported.

  Support for the S3C2400 and S3C24A0 series was never completed and the
  corresponding code has been removed after a while.  If someone wishes to
  revive this effort, partial support can be retrieved from earlier Linux
  versions.

  The S3C2416 and S3C2450 devices are very similar and S3C2450 support is
  included under the arch/arm/mach-s3c directory. Note, while core
  support for these SoCs is in, work on some of the extra peripherals
  and extra interrupts is still ongoing.

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

  A generic S3C2410 configuration is provided, and can be used as the
  default by `make s3c2410_defconfig`. This configuration has support
  for all the machines, and the commonly used features on them.

  Certain machines may have their own default configurations as well,
  please check the machine specific documentation.

Layout
------

  The core support files, register, kernel and paltform data are located in the
  platform code contained in arch/arm/mach-s3c with headers in
  arch/arm/mach-s3c/include

arch/arm/mach-s3c:

  Files in here are either common to all the s3c24xx family,
  or are common to only some of them with names to indicate this
  status. The files that are not common to all are generally named
  with the initial cpu they support in the series to ensure a short
  name without any possibility of confusion with newer devices.

  As an example, initially s3c244x would cover s3c2440 and s3c2442, but
  with the s3c2443 which does not share many of the same drivers in
  this directory, the name becomes invalid. We stick to s3c2440-<x>
  to indicate a driver that is s3c2440 and s3c2442 compatible.

  This does mean that to find the status of any given SoC, a number
  of directories may need to be searched.

Machines
--------

  The currently supported machines are as follows:

  Simtec Electronics EB2410ITX (BAST)

    A general purpose development board, see EB2410ITX.txt for further
    details

  Simtec Electronics IM2440D20 (Osiris)

    CPU Module from Simtec Electronics, with a S3C2440A CPU, nand flash
    and a PCMCIA controller.

  Samsung SMDK2410

    Samsung's own development board, geared for PDA work.

  Samsung/Aiji SMDK2412

    The S3C2412 version of the SMDK2440.

  Samsung/Aiji SMDK2413

    The S3C2412 version of the SMDK2440.

  Samsung/Meritech SMDK2440

    The S3C2440 compatible version of the SMDK2440, which has the
    option of an S3C2440 or S3C2442 CPU module.

  Thorcom VR1000

    Custom embedded board

  HP IPAQ 1940

    Handheld (IPAQ), available in several varieties

  HP iPAQ rx3715

    S3C2440 based IPAQ, with a number of variations depending on
    features shipped.

  Acer N30

    A S3C2410 based PDA from Acer.  There is a Wiki page at
    http://handhelds.org/moin/moin.cgi/AcerN30Documentation .

  AML M5900

    American Microsystems' M5900

  Nex Vision Nexcoder
  Nex Vision Otom

    Two machines by Nex Vision

Adding New Machines
-------------------

  The architecture has been designed to support as many machines as can
  be configured for it in one kernel build, and any future additions
  should keep this in mind before altering items outside of their own
  machine files.

  Machine definitions should be kept in arch/arm/mach-s3c,
  and there are a number of examples that can be looked at.

  Read the kernel patch submission policies as well as the
  Documentation/arm directory before submitting patches. The
  ARM kernel series is managed by Russell King, and has a patch system
  located at http://www.arm.linux.org.uk/developer/patches/
  as well as mailing lists that can be found from the same site.

  As a courtesy, please notify <ben-linux@fluff.org> of any new
  machines or other modifications.

  Any large scale modifications, or new drivers should be discussed
  on the ARM kernel mailing list (linux-arm-kernel) before being
  attempted. See http://www.arm.linux.org.uk/mailinglists/ for the
  mailing list information.

I2C
---

  The hardware I2C core in the CPU is supported in single master
  mode, and can be configured via platform data.

RTC
---

  Support for the onboard RTC unit, including alarm function.

  This has recently been upgraded to use the new RTC core,
  and the module has been renamed to rtc-s3c to fit in with
  the new rtc naming scheme.

Watchdog
--------

  The onchip watchdog is available via the standard watchdog
  interface.

NAND
----

  The current kernels now have support for the s3c2410 NAND
  controller. If there are any problems the latest linux-mtd
  code can be found from http://www.linux-mtd.infradead.org/

  For more information see Documentation/arm/samsung-s3c24xx/nand.rst

SD/MMC
------

  The SD/MMC hardware pre S3C2443 is supported in the current
  kernel, the driver is drivers/mmc/host/s3cmci.c and supports
  1 and 4 bit SD or MMC cards.

  The SDIO behaviour of this driver has not been fully tested. There is no
  current support for hardware SDIO interrupts.

Serial
------

  The s3c2410 serial driver provides support for the internal
  serial ports. These devices appear as /dev/ttySAC0 through 3.

  To create device nodes for these, use the following commands

    mknod ttySAC0 c 204 64
    mknod ttySAC1 c 204 65
    mknod ttySAC2 c 204 66

GPIO
----

  The core contains support for manipulating the GPIO, see the
  documentation in GPIO.txt in the same directory as this file.

  Newer kernels carry GPIOLIB, and support is being moved towards
  this with some of the older support in line to be removed.

  As of v2.6.34, the move towards using gpiolib support is almost
  complete, and very little of the old calls are left.

  See Documentation/arm/samsung-s3c24xx/gpio.rst for the S3C24XX specific
  support and Documentation/arm/samsung/gpio.rst for the core Samsung
  implementation.

Clock Management
----------------

  The core provides the interface defined in the header file
  include/asm-arm/hardware/clock.h, to allow control over the
  various clock units

Suspend to RAM
--------------

  For boards that provide support for suspend to RAM, the
  system can be placed into low power suspend.

  See Suspend.txt for more information.

SPI
---

  SPI drivers are available for both the in-built hardware
  (although there is no DMA support yet) and a generic
  GPIO based solution.

LEDs
----

  There is support for GPIO based LEDs via a platform driver
  in the LED subsystem.

Platform Data
-------------

  Whenever a device has platform specific data that is specified
  on a per-machine basis, care should be taken to ensure the
  following:

    1) that default data is not left in the device to confuse the
       driver if a machine does not set it at startup

    2) the data should (if possible) be marked as __initdata,
       to ensure that the data is thrown away if the machine is
       not the one currently in use.

       The best way of doing this is to make a function that
       kmalloc()s an area of memory, and copies the __initdata
       and then sets the relevant device's platform data. Making
       the function `__init` takes care of ensuring it is discarded
       with the rest of the initialisation code::

         static __init void s3c24xx_xxx_set_platdata(struct xxx_data *pd)
         {
             struct s3c2410_xxx_mach_info *npd;

	   npd = kmalloc(sizeof(struct s3c2410_xxx_mach_info), GFP_KERNEL);
	   if (npd) {
	      memcpy(npd, pd, sizeof(struct s3c2410_xxx_mach_info));
	      s3c_device_xxx.dev.platform_data = npd;
	   } else {
                printk(KERN_ERR "no memory for xxx platform data\n");
	   }
	}

	Note, since the code is marked as __init, it should not be
	exported outside arch/arm/mach-s3c/, or exported to
	modules via EXPORT_SYMBOL() and related functions.

Port Contributors
-----------------

  Ben Dooks (BJD)
  Vincent Sanders
  Herbert Potzl
  Arnaud Patard (RTP)
  Roc Wu
  Klaus Fetscher
  Dimitry Andric
  Shannon Holland
  Guillaume Gourat (NexVision)
  Christer Weinigel (wingel) (Acer N30)
  Lucas Correia Villa Real (S3C2400 port)

Document Author
---------------

Ben Dooks, Copyright 2004-2006 Simtec Electronics


code:
==========================
S3C2412 ARM Linux Overview
==========================

Introduction
------------

  The S3C2412 is part of the S3C24XX range of ARM9 System-on-Chip CPUs
  from Samsung. This part has an ARM926-EJS core, capable of running up
  to 266MHz (see data-sheet for more information)

Clock
-----

  The core clock code provides a set of clocks to the drivers, and allows
  for source selection and a number of other features.

Power
-----

  No support for suspend/resume to RAM in the current system.

DMA
---

  No current support for DMA.

GPIO
----

  There is support for setting the GPIO to input/output/special function
  and reading or writing to them.

UART
----

  The UART hardware is similar to the S3C2440, and is supported by the
  s3c2410 driver in the drivers/serial directory.

NAND
----

  The NAND hardware is similar to the S3C2440, and is supported by the
  s3c2410 driver in the drivers/mtd/nand/raw directory.

USB Host
--------

  The USB hardware is similar to the S3C2410, with extended clock source
  control. The OHCI portion is supported by the ohci-s3c2410 driver, and
  the clock control selection is supported by the core clock code.

USB Device
----------

  No current support in the kernel

IRQs
----

  All the standard, and external interrupt sources are supported. The
  extra sub-sources are not yet supported.

RTC
---

  The RTC hardware is similar to the S3C2410, and is supported by the
  s3c2410-rtc driver.

Watchdog
--------

  The watchdog hardware is the same as the S3C2410, and is supported by
  the s3c2410_wdt driver.

MMC/SD/SDIO
-----------

  No current support for the MMC/SD/SDIO block.

IIC
---

  The IIC hardware is the same as the S3C2410, and is supported by the
  i2c-s3c24xx driver.

IIS
---

  No current support for the IIS interface.

SPI
---

  No current support for the SPI interfaces.

ATA
---

  No current support for the on-board ATA block.

Document Author
---------------

Ben Dooks, Copyright 2006 Simtec Electronics


code:
==========================
S3C2413 ARM Linux Overview
==========================

Introduction
------------

  The S3C2413 is an extended version of the S3C2412, with an camera
  interface and mobile DDR memory support. See the S3C2412 support
  documentation for more information.

Camera Interface
----------------

  This block is currently not supported.

Document Author
---------------

Ben Dooks, Copyright 2006 Simtec Electronics


code:
=========================
Samsung/Meritech SMDK2440
=========================

Introduction
------------

  The SMDK2440 is a two part evaluation board for the Samsung S3C2440
  processor. It includes support for LCD, SmartMedia, Audio, SD and
  10MBit Ethernet, and expansion headers for various signals, including
  the camera and unused GPIO.

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

  To set the default configuration, use `make smdk2440_defconfig` which
  will configure the common features of this board, or use
  `make s3c2410_config` to include support for all s3c2410/s3c2440 machines

Support
-------

  Ben Dooks' SMDK2440 site at http://www.fluff.org/ben/smdk2440/ which
  includes linux based USB download tools.

  Some of the h1940 patches that can be found from the H1940 project
  site at http://www.handhelds.org/projects/h1940.html can also be
  applied to this board.

Peripherals
-----------

  There is no current support for any of the extra peripherals on the
  base-board itself.

MTD
---

  The NAND flash should be supported by the in kernel MTD NAND support,
  NOR flash will be added later.

Maintainers
-----------

  This board is being maintained by Ben Dooks, for more info, see
  http://www.fluff.org/ben/smdk2440/

  Many thanks to Dimitry Andric of TomTom for the loan of the SMDK2440,
  and to Simtec Electronics for allowing me time to work on this.

(c) 2004 Ben Dooks


code:
=======================
S3C24XX Suspend Support
=======================

Introduction
------------

  The S3C24XX supports a low-power suspend mode, where the SDRAM is kept
  in Self-Refresh mode, and all but the essential peripheral blocks are
  powered down. For more information on how this works, please look
  at the relevant CPU datasheet from Samsung.

Requirements
------------

  1) A bootloader that can support the necessary resume operation

  2) Support for at least 1 source for resume

  3) CONFIG_PM enabled in the kernel

  4) Any peripherals that are going to be powered down at the same
     time require suspend/resume support.

Resuming
--------

  The S3C2410 user manual defines the process of sending the CPU to
  sleep and how it resumes. The default behaviour of the Linux code
  is to set the GSTATUS3 register to the physical address of the
  code to resume Linux operation.

  GSTATUS4 is currently left alone by the sleep code, and is free to
  use for any other purposes (for example, the EB2410ITX uses this to
  save memory configuration in).

Machine Support
---------------

  The machine specific functions must call the s3c_pm_init() function
  to say that its bootloader is capable of resuming. This can be as
  simple as adding the following to the machine's definition:

  INITMACHINE(s3c_pm_init)

  A board can do its own setup before calling s3c_pm_init, if it
  needs to setup anything else for power management support.

  There is currently no support for over-riding the default method of
  saving the resume address, if your board requires it, then contact
  the maintainer and discuss what is required.

  Note, the original method of adding an late_initcall() is wrong,
  and will end up initialising all compiled machines' pm init!

  The following is an example of code used for testing wakeup from
  an falling edge on IRQ_EINT0::

    static irqreturn_t button_irq(int irq, void *pw)
    {
	return IRQ_HANDLED;
    }

    statuc void __init machine_init(void)
    {
	...

	request_irq(IRQ_EINT0, button_irq, IRQF_TRIGGER_FALLING,
		   "button-irq-eint0", NULL);

	enable_irq_wake(IRQ_EINT0);

	s3c_pm_init();
    }

Debugging
---------

  There are several important things to remember when using PM suspend:

  1) The uart drivers will disable the clocks to the UART blocks when
     suspending, which means that use of printascii() or similar direct
     access to the UARTs will cause the debug to stop.

  2) While the pm code itself will attempt to re-enable the UART clocks,
     care should be taken that any external clock sources that the UARTs
     rely on are still enabled at that point.

  3) If any debugging is placed in the resume path, then it must have the
     relevant clocks and peripherals setup before use (ie, bootloader).

     For example, if you transmit a character from the UART, the baud
     rate and uart controls must be setup beforehand.

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

  The S3C2410 specific configuration in `System Type` defines various
  aspects of how the S3C2410 suspend and resume support is configured

  `S3C2410 PM Suspend debug`

    This option prints messages to the serial console before and after
    the actual suspend, giving detailed information on what is
    happening

  `S3C2410 PM Suspend Memory CRC`

    Allows the entire memory to be checksummed before and after the
    suspend to see if there has been any corruption of the contents.

    Note, the time to calculate the CRC is dependent on the CPU speed
    and the size of memory. For an 64Mbyte RAM area on an 200MHz
    S3C2410, this can take approximately 4 seconds to complete.

    This support requires the CRC32 function to be enabled.

  `S3C2410 PM Suspend CRC Chunksize (KiB)`

    Defines the size of memory each CRC chunk covers. A smaller value
    will mean that the CRC data block will take more memory, but will
    identify any faults with better precision

Document Author
---------------

Ben Dooks, Copyright 2004 Simtec Electronics


code:
========================
S3C24XX USB Host support
========================

Introduction
------------

  This document details the S3C2410/S3C2440 in-built OHCI USB host support.

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

  Enable at least the following kernel options:

  menuconfig::

   Device Drivers  --->
     USB support  --->
       <*> Support for Host-side USB
       <*>   OHCI HCD support

  .config:

    - CONFIG_USB
    - CONFIG_USB_OHCI_HCD

  Once these options are configured, the standard set of USB device
  drivers can be configured and used.

Board Support
-------------

  The driver attaches to a platform device, which will need to be
  added by the board specific support file in arch/arm/mach-s3c,
  such as mach-bast.c or mach-smdk2410.c

  The platform device's platform_data field is only needed if the
  board implements extra power control or over-current monitoring.

  The OHCI driver does not ensure the state of the S3C2410's MISCCTRL
  register, so if both ports are to be used for the host, then it is
  the board support file's responsibility to ensure that the second
  port is configured to be connected to the OHCI core.

Platform Data
-------------

  See include/linux/platform_data/usb-ohci-s3c2410.h for the
  descriptions of the platform device data. An implementation
  can be found in arch/arm/mach-s3c/simtec-usb.c .

  The `struct s3c2410_hcd_info` contains a pair of functions
  that get called to enable over-current detection, and to
  control the port power status.

  The ports are numbered 0 and 1.

  power_control:
    Called to enable or disable the power on the port.

  enable_oc:
    Called to enable or disable the over-current monitoring.
    This should claim or release the resources being used to
    check the power condition on the port, such as an IRQ.

  report_oc:
    The OHCI driver fills this field in for the over-current code
    to call when there is a change to the over-current state on
    an port. The ports argument is a bitmask of 1 bit per port,
    with bit X being 1 for an over-current on port X.

    The function s3c2410_usb_report_oc() has been provided to
    ensure this is called correctly.

  port[x]:
    This is struct describes each port, 0 or 1. The platform driver
    should set the flags field of each port to S3C_HCDFLG_USED if
    the port is enabled.

Document Author
---------------

Ben Dooks, Copyright 2005 Simtec Electronics


code:
==========================================================
Interface between kernel and boot loaders on Exynos boards
==========================================================

Author: Krzysztof Kozlowski

Date  : 6 June 2015

The document tries to describe currently used interface between Linux kernel
and boot loaders on Samsung Exynos based boards. This is not a definition
of interface but rather a description of existing state, a reference
for information purpose only.

In the document "boot loader" means any of following: U-boot, proprietary
SBOOT or any other firmware for ARMv7 and ARMv8 initializing the board before
executing kernel.

1. Non-Secure mode

Address:      sysram_ns_base_addr

============= ============================================ ==================
Offset        Value                                        Purpose
============= ============================================ ==================
0x08          exynos_cpu_resume_ns, mcpm_entry_point       System suspend
0x0c          0x00000bad (Magic cookie)                    System suspend
0x1c          exynos4_secondary_startup                    Secondary CPU boot
0x1c + 4*cpu  exynos4_secondary_startup (Exynos4412)       Secondary CPU boot
0x20          0xfcba0d10 (Magic cookie)                    AFTR
0x24          exynos_cpu_resume_ns                         AFTR
0x28 + 4*cpu  0x8 (Magic cookie, Exynos3250)               AFTR
0x28          0x0 or last value during resume (Exynos542x) System suspend
============= ============================================ ==================

2. Secure mode

Address:      sysram_base_addr

============= ============================================ ==================
Offset        Value                                        Purpose
============= ============================================ ==================
0x00          exynos4_secondary_startup                    Secondary CPU boot
0x04          exynos4_secondary_startup (Exynos542x)       Secondary CPU boot
4*cpu         exynos4_secondary_startup (Exynos4412)       Secondary CPU boot
0x20          exynos_cpu_resume (Exynos4210 r1.0)          AFTR
0x24          0xfcba0d10 (Magic cookie, Exynos4210 r1.0)   AFTR
============= ============================================ ==================

Address:      pmu_base_addr

============= ============================================ ==================
Offset        Value                                        Purpose
============= ============================================ ==================
0x0800        exynos_cpu_resume                            AFTR, suspend
0x0800        mcpm_entry_point (Exynos542x with MCPM)      AFTR, suspend
0x0804        0xfcba0d10 (Magic cookie)                    AFTR
0x0804        0x00000bad (Magic cookie)                    System suspend
0x0814        exynos4_secondary_startup (Exynos4210 r1.1)  Secondary CPU boot
0x0818        0xfcba0d10 (Magic cookie, Exynos4210 r1.1)   AFTR
0x081C        exynos_cpu_resume (Exynos4210 r1.1)          AFTR
============= ============================================ ==================

3. Other (regardless of secure/non-secure mode)

Address:      pmu_base_addr

============= =============================== ===============================
Offset        Value                           Purpose
============= =============================== ===============================
0x0908        Non-zero                        Secondary CPU boot up indicator
                                              on Exynos3250 and Exynos542x
============= =============================== ===============================

4. Glossary

AFTR - ARM Off Top Running, a low power mode, Cortex cores and many other
modules are power gated, except the TOP modules
MCPM - Multi-Cluster Power Management


code:
#!/usr/bin/awk -f
#
# Copyright 2010 Ben Dooks <ben-linux@fluff.org>
#
# Released under GPLv2

# example usage
# ./clksrc-change-registers.awk arch/arm/plat-s5pc1xx/include/plat/regs-clock.h < src > dst

function extract_value(s)
{
    eqat = index(s, "=")
    comat = index(s, ",")
    return substr(s, eqat+2, (comat-eqat)-2)
}

function remove_brackets(b)
{
    return substr(b, 2, length(b)-2)
}

function splitdefine(l, p)
{
    r = split(l, tp)

    p[0] = tp[2]
    p[1] = remove_brackets(tp[3])
}

function find_length(f)
{
    if (0)
	printf "find_length " f "\n" > "/dev/stderr"

    if (f ~ /0x1/)
	return 1
    else if (f ~ /0x3/)
	return 2
    else if (f ~ /0x7/)
	return 3
    else if (f ~ /0xf/)
	return 4

    printf "unknown length " f "\n" > "/dev/stderr"
    exit
}

function find_shift(s)
{
    id = index(s, "<")
    if (id <= 0) {
	printf "cannot find shift " s "\n" > "/dev/stderr"
	exit
    }

    return substr(s, id+2)
}

BEGIN {
    if (ARGC < 2) {
	print "too few arguments" > "/dev/stderr"
	exit
    }

# read the header file and find the mask values that we will need
# to replace and create an associative array of values

    while (getline line < ARGV[1] > 0) {
	if (line ~ /\#define.*_MASK/ &&
	    !(line ~ /USB_SIG_MASK/)) {
	    splitdefine(line, fields)
	    name = fields[0]
	    if (0)
		printf "MASK " line "\n" > "/dev/stderr"
	    dmask[name,0] = find_length(fields[1])
	    dmask[name,1] = find_shift(fields[1])
	    if (0)
		printf "=> '" name "' LENGTH=" dmask[name,0] " SHIFT=" dmask[name,1] "\n" > "/dev/stderr"
	} else {
	}
    }

    delete ARGV[1]
}

/clksrc_clk.*=.*{/ {
    shift=""
    mask=""
    divshift=""
    reg_div=""
    reg_src=""
    indent=1

    print $0

    for(; indent >= 1;) {
	if ((getline line) <= 0) {
	    printf "unexpected end of file" > "/dev/stderr"
	    exit 1;
	}

	if (line ~ /\.shift/) {
	    shift = extract_value(line)
	} else if (line ~ /\.mask/) {
	    mask = extract_value(line)
	} else if (line ~ /\.reg_divider/) {
	    reg_div = extract_value(line)
	} else if (line ~ /\.reg_source/) {
	    reg_src = extract_value(line)
	} else if (line ~ /\.divider_shift/) {
	    divshift = extract_value(line)
	} else if (line ~ /{/) {
		indent++
		print line
	    } else if (line ~ /}/) {
	    indent--

	    if (indent == 0) {
		if (0) {
		    printf "shift '" shift   "' ='" dmask[shift,0] "'\n" > "/dev/stderr"
		    printf "mask  '" mask    "'\n" > "/dev/stderr"
		    printf "dshft '" divshift "'\n" > "/dev/stderr"
		    printf "rdiv  '" reg_div "'\n" > "/dev/stderr"
		    printf "rsrc  '" reg_src "'\n" > "/dev/stderr"
		}

		generated = mask
		sub(reg_src, reg_div, generated)

		if (0) {
		    printf "/* rsrc " reg_src " */\n"
		    printf "/* rdiv " reg_div " */\n"
		    printf "/* shift " shift " */\n"
		    printf "/* mask " mask " */\n"
		    printf "/* generated " generated " */\n"
		}

		if (reg_div != "") {
		    printf "\t.reg_div = { "
		    printf ".reg = " reg_div ", "
		    printf ".shift = " dmask[generated,1] ", "
		    printf ".size = " dmask[generated,0] ", "
		    printf "},\n"
		}

		printf "\t.reg_src = { "
		printf ".reg = " reg_src ", "
		printf ".shift = " dmask[mask,1] ", "
		printf ".size = " dmask[mask,0] ", "

		printf "},\n"

	    }

	    print line
	} else {
	    print line
	}

	if (0)
	    printf indent ":" line "\n" > "/dev/stderr"
    }
}

// && ! /clksrc_clk.*=.*{/ { print $0 }


code:
===========================
Samsung GPIO implementation
===========================

Introduction
------------

This outlines the Samsung GPIO implementation and the architecture
specific calls provided alongside the drivers/gpio core.

S3C24XX (Legacy)
----------------

See Documentation/arm/samsung-s3c24xx/gpio.rst for more information
about these devices. Their implementation has been brought into line
with the core samsung implementation described in this document.

GPIOLIB integration
-------------------

The gpio implementation uses gpiolib as much as possible, only providing
specific calls for the items that require Samsung specific handling, such
as pin special-function or pull resistor control.

GPIO numbering is synchronised between the Samsung and gpiolib system.

PIN configuration
-----------------

Pin configuration is specific to the Samsung architecture, with each SoC
registering the necessary information for the core gpio configuration
implementation to configure pins as necessary.

The s3c_gpio_cfgpin() and s3c_gpio_setpull() provide the means for a
driver or machine to change gpio configuration.

See arch/arm/mach-s3c/gpio-cfg.h for more information on these functions.


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

===========
Samsung SoC
===========

.. toctree::
   :maxdepth: 1

   gpio
   bootloader-interface
   overview


code:
==========================
Samsung ARM Linux Overview
==========================

Introduction
------------

  The Samsung range of ARM SoCs spans many similar devices, from the initial
  ARM9 through to the newest ARM cores. This document shows an overview of
  the current kernel support, how to use it and where to find the code
  that supports this.

  The currently supported SoCs are:

  - S3C24XX: See Documentation/arm/samsung-s3c24xx/overview.rst for full list
  - S3C64XX: S3C6400 and S3C6410
  - S5PC110 / S5PV210

S3C24XX Systems
---------------

  There is still documentation in Documnetation/arm/Samsung-S3C24XX/ which
  deals with the architecture and drivers specific to these devices.

  See Documentation/arm/samsung-s3c24xx/overview.rst for more information
  on the implementation details and specific support.

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

  A number of configurations are supplied, as there is no current way of
  unifying all the SoCs into one kernel.

  s5pc110_defconfig
	- S5PC110 specific default configuration
  s5pv210_defconfig
	- S5PV210 specific default configuration

Layout
------

  The directory layout is currently being restructured, and consists of
  several platform directories and then the machine specific directories
  of the CPUs being built for.

  plat-samsung provides the base for all the implementations, and is the
  last in the line of include directories that are processed for the build
  specific information. It contains the base clock, GPIO and device definitions
  to get the system running.

  plat-s3c24xx is for s3c24xx specific builds, see the S3C24XX docs.

  plat-s5p is for s5p specific builds, and contains common support for the
  S5P specific systems. Not all S5Ps use all the features in this directory
  due to differences in the hardware.

Layout changes
--------------

  The old plat-s3c and plat-s5pc1xx directories have been removed, with
  support moved to either plat-samsung or plat-s5p as necessary. These moves
  where to simplify the include and dependency issues involved with having
  so many different platform directories.

Port Contributors
-----------------

  Ben Dooks (BJD)
  Vincent Sanders
  Herbert Potzl
  Arnaud Patard (RTP)
  Roc Wu
  Klaus Fetscher
  Dimitry Andric
  Shannon Holland
  Guillaume Gourat (NexVision)
  Christer Weinigel (wingel) (Acer N30)
  Lucas Correia Villa Real (S3C2400 port)

Document Author
---------------

Copyright 2009-2010 Ben Dooks <ben-linux@fluff.org>


code:
=============================================
Kernel initialisation parameters on ARM Linux
=============================================

The following document describes the kernel initialisation parameter
structure, otherwise known as 'struct param_struct' which is used
for most ARM Linux architectures.

This structure is used to pass initialisation parameters from the
kernel loader to the Linux kernel proper, and may be short lived
through the kernel initialisation process.  As a general rule, it
should not be referenced outside of arch/arm/kernel/setup.c:setup_arch().

There are a lot of parameters listed in there, and they are described
below:

 page_size
   This parameter must be set to the page size of the machine, and
   will be checked by the kernel.

 nr_pages
   This is the total number of pages of memory in the system.  If
   the memory is banked, then this should contain the total number
   of pages in the system.

   If the system contains separate VRAM, this value should not
   include this information.

 ramdisk_size
   This is now obsolete, and should not be used.

 flags
   Various kernel flags, including:

    =====   ========================
    bit 0   1 = mount root read only
    bit 1   unused
    bit 2   0 = load ramdisk
    bit 3   0 = prompt for ramdisk
    =====   ========================

 rootdev
   major/minor number pair of device to mount as the root filesystem.

 video_num_cols / video_num_rows
   These two together describe the character size of the dummy console,
   or VGA console character size.  They should not be used for any other
   purpose.

   It's generally a good idea to set these to be either standard VGA, or
   the equivalent character size of your fbcon display.  This then allows
   all the bootup messages to be displayed correctly.

 video_x / video_y
   This describes the character position of cursor on VGA console, and
   is otherwise unused. (should not be used for other console types, and
   should not be used for other purposes).

 memc_control_reg
   MEMC chip control register for Acorn Archimedes and Acorn A5000
   based machines.  May be used differently by different architectures.

 sounddefault
   Default sound setting on Acorn machines.  May be used differently by
   different architectures.

 adfsdrives
   Number of ADFS/MFM disks.  May be used differently by different
   architectures.

 bytes_per_char_h / bytes_per_char_v
   These are now obsolete, and should not be used.

 pages_in_bank[4]
   Number of pages in each bank of the systems memory (used for RiscPC).
   This is intended to be used on systems where the physical memory
   is non-contiguous from the processors point of view.

 pages_in_vram
   Number of pages in VRAM (used on Acorn RiscPC).  This value may also
   be used by loaders if the size of the video RAM can't be obtained
   from the hardware.

 initrd_start / initrd_size
   This describes the kernel virtual start address and size of the
   initial ramdisk.

 rd_start
   Start address in sectors of the ramdisk image on a floppy disk.

 system_rev
   system revision number.

 system_serial_low / system_serial_high
   system 64-bit serial number

 mem_fclk_21285
   The speed of the external oscillator to the 21285 (footbridge),
   which control's the speed of the memory bus, timer & serial port.
   Depending upon the speed of the cpu its value can be between
   0-66 MHz. If no params are passed or a value of zero is passed,
   then a value of 50 Mhz is the default on 21285 architectures.

 paths[8][128]
   These are now obsolete, and should not be used.

 commandline
   Kernel command line parameters.  Details can be found elsewhere.


code:
========================
SPEAr ARM Linux Overview
========================

Introduction
------------

  SPEAr (Structured Processor Enhanced Architecture).
  weblink : http://www.st.com/spear

  The ST Microelectronics SPEAr range of ARM9/CortexA9 System-on-Chip CPUs are
  supported by the 'spear' platform of ARM Linux. Currently SPEAr1310,
  SPEAr1340, SPEAr300, SPEAr310, SPEAr320 and SPEAr600 SOCs are supported.

  Hierarchy in SPEAr is as follows:

  SPEAr (Platform)

	- SPEAr3XX (3XX SOC series, based on ARM9)
		- SPEAr300 (SOC)
			- SPEAr300 Evaluation Board
		- SPEAr310 (SOC)
			- SPEAr310 Evaluation Board
		- SPEAr320 (SOC)
			- SPEAr320 Evaluation Board
	- SPEAr6XX (6XX SOC series, based on ARM9)
		- SPEAr600 (SOC)
			- SPEAr600 Evaluation Board
	- SPEAr13XX (13XX SOC series, based on ARM CORTEXA9)
		- SPEAr1310 (SOC)
			- SPEAr1310 Evaluation Board
		- SPEAr1340 (SOC)
			- SPEAr1340 Evaluation Board

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

  A generic configuration is provided for each machine, and can be used as the
  default by::

	make spear13xx_defconfig
	make spear3xx_defconfig
	make spear6xx_defconfig

Layout
------

  The common files for multiple machine families (SPEAr3xx, SPEAr6xx and
  SPEAr13xx) are located in the platform code contained in arch/arm/plat-spear
  with headers in plat/.

  Each machine series have a directory with name arch/arm/mach-spear followed by
  series name. Like mach-spear3xx, mach-spear6xx and mach-spear13xx.

  Common file for machines of spear3xx family is mach-spear3xx/spear3xx.c, for
  spear6xx is mach-spear6xx/spear6xx.c and for spear13xx family is
  mach-spear13xx/spear13xx.c. mach-spear* also contain soc/machine specific
  files, like spear1310.c, spear1340.c spear300.c, spear310.c, spear320.c and
  spear600.c.  mach-spear* doesn't contains board specific files as they fully
  support Flattened Device Tree.

Document Author
---------------

  Viresh Kumar <vireshk@kernel.org>, (c) 2010-2012 ST Microelectronics


code:
======================
STi ARM Linux Overview
======================

Introduction
------------

  The ST Microelectronics Multimedia and Application Processors range of
  CortexA9 System-on-Chip are supported by the 'STi' platform of
  ARM Linux. Currently STiH415, STiH416 SOCs are supported with both
  B2000 and B2020 Reference boards.

configuration
-------------

  A generic configuration is provided for both STiH415/416, and can be used as the
  default by::

	make stih41x_defconfig

Layout
------

  All the files for multiple machine families (STiH415, STiH416, and STiG125)
  are located in the platform code contained in arch/arm/mach-sti

  There is a generic board board-dt.c in the mach folder which support
  Flattened Device Tree, which means, It works with any compatible board with
  Device Trees.

Document Author
---------------

  Srinivas Kandagatla <srinivas.kandagatla@st.com>, (c) 2013 ST Microelectronics


code:
================
STiH407 Overview
================

Introduction
------------

    The STiH407 is the new generation of SoC for Multi-HD, AVC set-top boxes
    and server/connected client application for satellite, cable, terrestrial
    and IP-STB markets.

    Features
    - ARM Cortex-A9 1.5 GHz dual core CPU (28nm)
    - SATA2, USB 3.0, PCIe, Gbit Ethernet

Document Author
---------------

  Maxime Coquelin <maxime.coquelin@st.com>, (c) 2014 ST Microelectronics


code:
================
STiH415 Overview
================

Introduction
------------

    The STiH415 is the next generation of HD, AVC set-top box processors
    for satellite, cable, terrestrial and IP-STB markets.

    Features:

    - ARM Cortex-A9 1.0 GHz, dual-core CPU
    - SATA2x2,USB 2.0x3, PCIe, Gbit Ethernet MACx2


code:
================
STiH416 Overview
================

Introduction
------------

    The STiH416 is the next generation of HD, AVC set-top box processors
    for satellite, cable, terrestrial and IP-STB markets.

    Features
    - ARM Cortex-A9 1.2 GHz dual core CPU
    - SATA2x2,USB 2.0x3, PCIe, Gbit Ethernet MACx2


code:
================
STiH418 Overview
================

Introduction
------------

    The STiH418 is the new generation of SoC for UHDp60 set-top boxes
    and server/connected client application for satellite, cable, terrestrial
    and IP-STB markets.

    Features
    - ARM Cortex-A9 1.5 GHz quad core CPU (28nm)
    - SATA2, USB 3.0, PCIe, Gbit Ethernet
    - HEVC L5.1 Main 10
    - VP9

Document Author
---------------

  Maxime Coquelin <maxime.coquelin@st.com>, (c) 2015 ST Microelectronics


code:
========================
STM32 ARM Linux Overview
========================

Introduction
------------

The STMicroelectronics STM32 family of Cortex-A microprocessors (MPUs) and
Cortex-M microcontrollers (MCUs) are supported by the 'STM32' platform of
ARM Linux.

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

For MCUs, use the provided default configuration:
        make stm32_defconfig
For MPUs, use multi_v7 configuration:
        make multi_v7_defconfig

Layout
------

All the files for multiple machine families are located in the platform code
contained in arch/arm/mach-stm32

There is a generic board board-dt.c in the mach folder which support
Flattened Device Tree, which means, it works with any compatible board with
Device Trees.

:Authors:

- Maxime Coquelin <mcoquelin.stm32@gmail.com>
- Ludovic Barre <ludovic.barre@st.com>
- Gerald Baeza <gerald.baeza@st.com>


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

=======================
STM32 DMA-MDMA chaining
=======================

Introduction
------------

  This document describes the STM32 DMA-MDMA chaining feature. But before going
  further, let's introduce the peripherals involved.

  To offload data transfers from the CPU, STM32 microprocessors (MPUs) embed
  direct memory access controllers (DMA).

  STM32MP1 SoCs embed both STM32 DMA and STM32 MDMA controllers. STM32 DMA
  request routing capabilities are enhanced by a DMA request multiplexer
  (STM32 DMAMUX).

  **STM32 DMAMUX**

  STM32 DMAMUX routes any DMA request from a given peripheral to any STM32 DMA
  controller (STM32MP1 counts two STM32 DMA controllers) channels.

  **STM32 DMA**

  STM32 DMA is mainly used to implement central data buffer storage (usually in
  the system SRAM) for different peripheral. It can access external RAMs but
  without the ability to generate convenient burst transfer ensuring the best
  load of the AXI.

  **STM32 MDMA**

  STM32 MDMA (Master DMA) is mainly used to manage direct data transfers between
  RAM data buffers without CPU intervention. It can also be used in a
  hierarchical structure that uses STM32 DMA as first level data buffer
  interfaces for AHB peripherals, while the STM32 MDMA acts as a second level
  DMA with better performance. As a AXI/AHB master, STM32 MDMA can take control
  of the AXI/AHB bus.

Principles
----------

  STM32 DMA-MDMA chaining feature relies on the strengths of STM32 DMA and
  STM32 MDMA controllers.

  STM32 DMA has a circular Double Buffer Mode (DBM). At each end of transaction
  (when DMA data counter - DMA_SxNDTR - reaches 0), the memory pointers
  (configured with DMA_SxSM0AR and DMA_SxM1AR) are swapped and the DMA data
  counter is automatically reloaded. This allows the SW or the STM32 MDMA to
  process one memory area while the second memory area is being filled/used by
  the STM32 DMA transfer.

  With STM32 MDMA linked-list mode, a single request initiates the data array
  (collection of nodes) to be transferred until the linked-list pointer for the
  channel is null. The channel transfer complete of the last node is the end of
  transfer, unless first and last nodes are linked to each other, in such a
  case, the linked-list loops on to create a circular MDMA transfer.

  STM32 MDMA has direct connections with STM32 DMA. This enables autonomous
  communication and synchronization between peripherals, thus saving CPU
  resources and bus congestion. Transfer Complete signal of STM32 DMA channel
  can triggers STM32 MDMA transfer. STM32 MDMA can clear the request generated
  by the STM32 DMA by writing to its Interrupt Clear register (whose address is
  stored in MDMA_CxMAR, and bit mask in MDMA_CxMDR).

  .. table:: STM32 MDMA interconnect table with STM32 DMA

    +--------------+----------------+-----------+------------+
    | STM32 DMAMUX | STM32 DMA      | STM32 DMA | STM32 MDMA |
    | channels     | channels       | Transfer  | request    |
    |              |                | complete  |            |
    |              |                | signal    |            |
    +==============+================+===========+============+
    | Channel *0*  | DMA1 channel 0 | dma1_tcf0 | *0x00*     |
    +--------------+----------------+-----------+------------+
    | Channel *1*  | DMA1 channel 1 | dma1_tcf1 | *0x01*     |
    +--------------+----------------+-----------+------------+
    | Channel *2*  | DMA1 channel 2 | dma1_tcf2 | *0x02*     |
    +--------------+----------------+-----------+------------+
    | Channel *3*  | DMA1 channel 3 | dma1_tcf3 | *0x03*     |
    +--------------+----------------+-----------+------------+
    | Channel *4*  | DMA1 channel 4 | dma1_tcf4 | *0x04*     |
    +--------------+----------------+-----------+------------+
    | Channel *5*  | DMA1 channel 5 | dma1_tcf5 | *0x05*     |
    +--------------+----------------+-----------+------------+
    | Channel *6*  | DMA1 channel 6 | dma1_tcf6 | *0x06*     |
    +--------------+----------------+-----------+------------+
    | Channel *7*  | DMA1 channel 7 | dma1_tcf7 | *0x07*     |
    +--------------+----------------+-----------+------------+
    | Channel *8*  | DMA2 channel 0 | dma2_tcf0 | *0x08*     |
    +--------------+----------------+-----------+------------+
    | Channel *9*  | DMA2 channel 1 | dma2_tcf1 | *0x09*     |
    +--------------+----------------+-----------+------------+
    | Channel *10* | DMA2 channel 2 | dma2_tcf2 | *0x0A*     |
    +--------------+----------------+-----------+------------+
    | Channel *11* | DMA2 channel 3 | dma2_tcf3 | *0x0B*     |
    +--------------+----------------+-----------+------------+
    | Channel *12* | DMA2 channel 4 | dma2_tcf4 | *0x0C*     |
    +--------------+----------------+-----------+------------+
    | Channel *13* | DMA2 channel 5 | dma2_tcf5 | *0x0D*     |
    +--------------+----------------+-----------+------------+
    | Channel *14* | DMA2 channel 6 | dma2_tcf6 | *0x0E*     |
    +--------------+----------------+-----------+------------+
    | Channel *15* | DMA2 channel 7 | dma2_tcf7 | *0x0F*     |
    +--------------+----------------+-----------+------------+

  STM32 DMA-MDMA chaining feature then uses a SRAM buffer. STM32MP1 SoCs embed
  three fast access static internal RAMs of various size, used for data storage.
  Due to STM32 DMA legacy (within microcontrollers), STM32 DMA performances are
  bad with DDR, while they are optimal with SRAM. Hence the SRAM buffer used
  between STM32 DMA and STM32 MDMA. This buffer is split in two equal periods
  and STM32 DMA uses one period while STM32 MDMA uses the other period
  simultaneously.
  ::

                    dma[1:2]-tcf[0:7]
                   .----------------.
     ____________ '    _________     V____________
    | STM32 DMA  |    /  __|>_  \    | STM32 MDMA |
    |------------|   |  /     \  |   |------------|
    | DMA_SxM0AR |<=>| | SRAM  | |<=>| []-[]...[] |
    | DMA_SxM1AR |   |  \_____/  |   |            |
    |____________|    \___<|____/    |____________|

  STM32 DMA-MDMA chaining uses (struct dma_slave_config).peripheral_config to
  exchange the parameters needed to configure MDMA. These parameters are
  gathered into a u32 array with three values:

  * the STM32 MDMA request (which is actually the DMAMUX channel ID),
  * the address of the STM32 DMA register to clear the Transfer Complete
    interrupt flag,
  * the mask of the Transfer Complete interrupt flag of the STM32 DMA channel.

Device Tree updates for STM32 DMA-MDMA chaining support
-------------------------------------------------------

  **1. Allocate a SRAM buffer**

    SRAM device tree node is defined in SoC device tree. You can refer to it in
    your board device tree to define your SRAM pool.
    ::

          &sram {
                  my_foo_device_dma_pool: dma-sram@0 {
                          reg = <0x0 0x1000>;
                  };
          };

    Be careful of the start index, in case there are other SRAM consumers.
    Define your pool size strategically: to optimise chaining, the idea is that
    STM32 DMA and STM32 MDMA can work simultaneously, on each buffer of the
    SRAM.
    If the SRAM period is greater than the expected DMA transfer, then STM32 DMA
    and STM32 MDMA will work sequentially instead of simultaneously. It is not a
    functional issue but it is not optimal.

    Don't forget to refer to your SRAM pool in your device node. You need to
    define a new property.
    ::

          &my_foo_device {
                  ...
                  my_dma_pool = &my_foo_device_dma_pool;
          };

    Then get this SRAM pool in your foo driver and allocate your SRAM buffer.

  **2. Allocate a STM32 DMA channel and a STM32 MDMA channel**

    You need to define an extra channel in your device tree node, in addition to
    the one you should already have for "classic" DMA operation.

    This new channel must be taken from STM32 MDMA channels, so, the phandle of
    the DMA controller to use is the MDMA controller's one.
    ::

          &my_foo_device {
                  [...]
                  my_dma_pool = &my_foo_device_dma_pool;
                  dmas = <&dmamux1 ...>,                // STM32 DMA channel
                         <&mdma1 0 0x3 0x1200000a 0 0>; // + STM32 MDMA channel
          };

    Concerning STM32 MDMA bindings:

    1. The request line number : whatever the value here, it will be overwritten
    by MDMA driver with the STM32 DMAMUX channel ID passed through
    (struct dma_slave_config).peripheral_config

    2. The priority level : choose Very High (0x3) so that your channel will
    take priority other the other during request arbitration

    3. A 32bit mask specifying the DMA channel configuration : source and
    destination address increment, block transfer with 128 bytes per single
    transfer

    4. The 32bit value specifying the register to be used to acknowledge the
    request: it will be overwritten by MDMA driver, with the DMA channel
    interrupt flag clear register address passed through
    (struct dma_slave_config).peripheral_config

    5. The 32bit mask specifying the value to be written to acknowledge the
    request: it will be overwritten by MDMA driver, with the DMA channel
    Transfer Complete flag passed through
    (struct dma_slave_config).peripheral_config

Driver updates for STM32 DMA-MDMA chaining support in foo driver
----------------------------------------------------------------

  **0. (optional) Refactor the original sg_table if dmaengine_prep_slave_sg()**

    In case of dmaengine_prep_slave_sg(), the original sg_table can't be used as
    is. Two new sg_tables must be created from the original one. One for
    STM32 DMA transfer (where memory address targets now the SRAM buffer instead
    of DDR buffer) and one for STM32 MDMA transfer (where memory address targets
    the DDR buffer).

    The new sg_list items must fit SRAM period length. Here is an example for
    DMA_DEV_TO_MEM:
    ::

      /*
        * Assuming sgl and nents, respectively the initial scatterlist and its
        * length.
        * Assuming sram_dma_buf and sram_period, respectively the memory
        * allocated from the pool for DMA usage, and the length of the period,
        * which is half of the sram_buf size.
        */
      struct sg_table new_dma_sgt, new_mdma_sgt;
      struct scatterlist *s, *_sgl;
      dma_addr_t ddr_dma_buf;
      u32 new_nents = 0, len;
      int i;

      /* Count the number of entries needed */
      for_each_sg(sgl, s, nents, i)
              if (sg_dma_len(s) > sram_period)
                      new_nents += DIV_ROUND_UP(sg_dma_len(s), sram_period);
              else
                      new_nents++;

      /* Create sg table for STM32 DMA channel */
      ret = sg_alloc_table(&new_dma_sgt, new_nents, GFP_ATOMIC);
      if (ret)
              dev_err(dev, "DMA sg table alloc failed\n");

      for_each_sg(new_dma_sgt.sgl, s, new_dma_sgt.nents, i) {
              _sgl = sgl;
              sg_dma_len(s) = min(sg_dma_len(_sgl), sram_period);
              /* Targets the beginning = first half of the sram_buf */
              s->dma_address = sram_buf;
              /*
                * Targets the second half of the sram_buf
                * for odd indexes of the item of the sg_list
                */
              if (i & 1)
                      s->dma_address += sram_period;
      }

      /* Create sg table for STM32 MDMA channel */
      ret = sg_alloc_table(&new_mdma_sgt, new_nents, GFP_ATOMIC);
      if (ret)
              dev_err(dev, "MDMA sg_table alloc failed\n");

      _sgl = sgl;
      len = sg_dma_len(sgl);
      ddr_dma_buf = sg_dma_address(sgl);
      for_each_sg(mdma_sgt.sgl, s, mdma_sgt.nents, i) {
              size_t bytes = min_t(size_t, len, sram_period);

              sg_dma_len(s) = bytes;
              sg_dma_address(s) = ddr_dma_buf;
              len -= bytes;

              if (!len && sg_next(_sgl)) {
                      _sgl = sg_next(_sgl);
                      len = sg_dma_len(_sgl);
                      ddr_dma_buf = sg_dma_address(_sgl);
              } else {
                      ddr_dma_buf += bytes;
              }
      }

    Don't forget to release these new sg_tables after getting the descriptors
    with dmaengine_prep_slave_sg().

  **1. Set controller specific parameters**

    First, use dmaengine_slave_config() with a struct dma_slave_config to
    configure STM32 DMA channel. You just have to take care of DMA addresses,
    the memory address (depending on the transfer direction) must point on your
    SRAM buffer, and set (struct dma_slave_config).peripheral_size != 0.

    STM32 DMA driver will check (struct dma_slave_config).peripheral_size to
    determine if chaining is being used or not. If it is used, then STM32 DMA
    driver fills (struct dma_slave_config).peripheral_config with an array of
    three u32 : the first one containing STM32 DMAMUX channel ID, the second one
    the channel interrupt flag clear register address, and the third one the
    channel Transfer Complete flag mask.

    Then, use dmaengine_slave_config with another struct dma_slave_config to
    configure STM32 MDMA channel. Take care of DMA addresses, the device address
    (depending on the transfer direction) must point on your SRAM buffer, and
    the memory address must point to the buffer originally used for "classic"
    DMA operation. Use the previous (struct dma_slave_config).peripheral_size
    and .peripheral_config that have been updated by STM32 DMA driver, to set
    (struct dma_slave_config).peripheral_size and .peripheral_config of the
    struct dma_slave_config to configure STM32 MDMA channel.
    ::

      struct dma_slave_config dma_conf;
      struct dma_slave_config mdma_conf;

      memset(&dma_conf, 0, sizeof(dma_conf));
      [...]
      config.direction = DMA_DEV_TO_MEM;
      config.dst_addr = sram_dma_buf;        // SRAM buffer
      config.peripheral_size = 1;            // peripheral_size != 0 => chaining

      dmaengine_slave_config(dma_chan, &dma_config);

      memset(&mdma_conf, 0, sizeof(mdma_conf));
      config.direction = DMA_DEV_TO_MEM;
      mdma_conf.src_addr = sram_dma_buf;     // SRAM buffer
      mdma_conf.dst_addr = rx_dma_buf;       // original memory buffer
      mdma_conf.peripheral_size = dma_conf.peripheral_size;       // <- dma_conf
      mdma_conf.peripheral_config = dma_config.peripheral_config; // <- dma_conf

      dmaengine_slave_config(mdma_chan, &mdma_conf);

  **2. Get a descriptor for STM32 DMA channel transaction**

    In the same way you get your descriptor for your "classic" DMA operation,
    you just have to replace the original sg_list (in case of
    dmaengine_prep_slave_sg()) with the new sg_list using SRAM buffer, or to
    replace the original buffer address, length and period (in case of
    dmaengine_prep_dma_cyclic()) with the new SRAM buffer.

  **3. Get a descriptor for STM32 MDMA channel transaction**

    If you previously get descriptor (for STM32 DMA) with

    * dmaengine_prep_slave_sg(), then use dmaengine_prep_slave_sg() for
      STM32 MDMA;
    * dmaengine_prep_dma_cyclic(), then use dmaengine_prep_dma_cyclic() for
      STM32 MDMA.

    Use the new sg_list using SRAM buffer (in case of dmaengine_prep_slave_sg())
    or, depending on the transfer direction, either the original DDR buffer (in
    case of DMA_DEV_TO_MEM) or the SRAM buffer (in case of DMA_MEM_TO_DEV), the
    source address being previously set with dmaengine_slave_config().

  **4. Submit both transactions**

    Before submitting your transactions, you may need to define on which
    descriptor you want a callback to be called at the end of the transfer
    (dmaengine_prep_slave_sg()) or the period (dmaengine_prep_dma_cyclic()).
    Depending on the direction, set the callback on the descriptor that finishes
    the overal transfer:

    * DMA_DEV_TO_MEM: set the callback on the "MDMA" descriptor
    * DMA_MEM_TO_DEV: set the callback on the "DMA" descriptor

    Then, submit the descriptors whatever the order, with dmaengine_tx_submit().

  **5. Issue pending requests (and wait for callback notification)**

  As STM32 MDMA channel transfer is triggered by STM32 DMA, you must issue
  STM32 MDMA channel before STM32 DMA channel.

  If any, your callback will be called to warn you about the end of the overal
  transfer or the period completion.

  Don't forget to terminate both channels. STM32 DMA channel is configured in
  cyclic Double-Buffer mode so it won't be disabled by HW, you need to terminate
  it. STM32 MDMA channel will be stopped by HW in case of sg transfer, but not
  in case of cyclic transfer. You can terminate it whatever the kind of transfer.

  **STM32 DMA-MDMA chaining DMA_MEM_TO_DEV special case**

  STM32 DMA-MDMA chaining in DMA_MEM_TO_DEV is a special case. Indeed, the
  STM32 MDMA feeds the SRAM buffer with the DDR data, and the STM32 DMA reads
  data from SRAM buffer. So some data (the first period) have to be copied in
  SRAM buffer when the STM32 DMA starts to read.

  A trick could be pausing the STM32 DMA channel (that will raise a Transfer
  Complete signal, triggering the STM32 MDMA channel), but the first data read
  by the STM32 DMA could be "wrong". The proper way is to prepare the first SRAM
  period with dmaengine_prep_dma_memcpy(). Then this first period should be
  "removed" from the sg or the cyclic transfer.

  Due to this complexity, rather use the STM32 DMA-MDMA chaining for
  DMA_DEV_TO_MEM and keep the "classic" DMA usage for DMA_MEM_TO_DEV, unless
  you're not afraid.

Resources
---------

  Application note, datasheet and reference manual are available on ST website
  (STM32MP1_).

  Dedicated focus on three application notes (AN5224_, AN4031_ & AN5001_)
  dealing with STM32 DMAMUX, STM32 DMA and STM32 MDMA.

.. _STM32MP1: https://www.st.com/en/microcontrollers-microprocessors/stm32mp1-series.html
.. _AN5224: https://www.st.com/resource/en/application_note/an5224-stm32-dmamux-the-dma-request-router-stmicroelectronics.pdf
.. _AN4031: https://www.st.com/resource/en/application_note/dm00046011-using-the-stm32f2-stm32f4-and-stm32f7-series-dma-controller-stmicroelectronics.pdf
.. _AN5001: https://www.st.com/resource/en/application_note/an5001-stm32cube-expansion-package-for-stm32h7-series-mdma-stmicroelectronics.pdf

:Authors:

- Amelie Delaunay <amelie.delaunay@foss.st.com>


code:
==================
STM32F429 Overview
==================

Introduction
------------

The STM32F429 is a Cortex-M4 MCU aimed at various applications.
It features:

- ARM Cortex-M4 up to 180MHz with FPU
- 2MB internal Flash Memory
- External memory support through FMC controller (PSRAM, SDRAM, NOR, NAND)
- I2C, SPI, SAI, CAN, USB OTG, Ethernet controllers
- LCD controller & Camera interface
- Cryptographic processor

Resources
---------

Datasheet and reference manual are publicly available on ST website (STM32F429_).

.. _STM32F429: http://www.st.com/web/en/catalog/mmc/FM141/SC1169/SS1577/LN1806?ecmp=stm32f429-439_pron_pr-ces2014_nov2013

:Authors: Maxime Coquelin <mcoquelin.stm32@gmail.com>


code:
==================
STM32F746 Overview
==================

Introduction
------------

The STM32F746 is a Cortex-M7 MCU aimed at various applications.
It features:

- Cortex-M7 core running up to @216MHz
- 1MB internal flash, 320KBytes internal RAM (+4KB of backup SRAM)
- FMC controller to connect SDRAM, NOR and NAND memories
- Dual mode QSPI
- SD/MMC/SDIO support
- Ethernet controller
- USB OTFG FS & HS controllers
- I2C, SPI, CAN busses support
- Several 16 & 32 bits general purpose timers
- Serial Audio interface
- LCD controller
- HDMI-CEC
- SPDIFRX

Resources
---------

Datasheet and reference manual are publicly available on ST website (STM32F746_).

.. _STM32F746: http://www.st.com/content/st_com/en/products/microcontrollers/stm32-32-bit-arm-cortex-mcus/stm32f7-series/stm32f7x6/stm32f746ng.html

:Authors: Alexandre Torgue <alexandre.torgue@st.com>


code:
==================
STM32F769 Overview
==================

Introduction
------------

The STM32F769 is a Cortex-M7 MCU aimed at various applications.
It features:

- Cortex-M7 core running up to @216MHz
- 2MB internal flash, 512KBytes internal RAM (+4KB of backup SRAM)
- FMC controller to connect SDRAM, NOR and NAND memories
- Dual mode QSPI
- SD/MMC/SDIO support*2
- Ethernet controller
- USB OTFG FS & HS controllers
- I2C*4, SPI*6, CAN*3 busses support
- Several 16 & 32 bits general purpose timers
- Serial Audio interface*2
- LCD controller
- HDMI-CEC
- DSI
- SPDIFRX
- MDIO salave interface

Resources
---------

Datasheet and reference manual are publicly available on ST website (STM32F769_).

.. _STM32F769: http://www.st.com/content/st_com/en/products/microcontrollers/stm32-32-bit-arm-cortex-mcus/stm32-high-performance-mcus/stm32f7-series/stm32f7x9/stm32f769ni.html

:Authors: Alexandre Torgue <alexandre.torgue@st.com>


code:
==================
STM32H743 Overview
==================

Introduction
------------

The STM32H743 is a Cortex-M7 MCU aimed at various applications.
It features:

- Cortex-M7 core running up to @400MHz
- 2MB internal flash, 1MBytes internal RAM
- FMC controller to connect SDRAM, NOR and NAND memories
- Dual mode QSPI
- SD/MMC/SDIO support
- Ethernet controller
- USB OTFG FS & HS controllers
- I2C, SPI, CAN busses support
- Several 16 & 32 bits general purpose timers
- Serial Audio interface
- LCD controller
- HDMI-CEC
- SPDIFRX
- DFSDM

Resources
---------

Datasheet and reference manual are publicly available on ST website (STM32H743_).

.. _STM32H743: http://www.st.com/en/microcontrollers/stm32h7x3.html?querycriteria=productId=LN2033

:Authors: Alexandre Torgue <alexandre.torgue@st.com>


code:
==================
STM32H750 Overview
==================

Introduction
------------

The STM32H750 is a Cortex-M7 MCU aimed at various applications.
It features:

- Cortex-M7 core running up to @480MHz
- 128K internal flash, 1MBytes internal RAM
- FMC controller to connect SDRAM, NOR and NAND memories
- Dual mode QSPI
- SD/MMC/SDIO support
- Ethernet controller
- USB OTFG FS & HS controllers
- I2C, SPI, CAN busses support
- Several 16 & 32 bits general purpose timers
- Serial Audio interface
- LCD controller
- HDMI-CEC
- SPDIFRX
- DFSDM

Resources
---------

Datasheet and reference manual are publicly available on ST website (STM32H750_).

.. _STM32H750: https://www.st.com/en/microcontrollers-microprocessors/stm32h750-value-line.html

:Authors: Dillon Min <dillon.minfei@gmail.com>


code:
===================
STM32MP13 Overview
===================

Introduction
------------

The STM32MP131/STM32MP133/STM32MP135 are Cortex-A MPU aimed at various applications.
They feature:

- One Cortex-A7 application core
- Standard memories interface support
- Standard connectivity, widely inherited from the STM32 MCU family
- Comprehensive security support

More details:

- Cortex-A7 core running up to @900MHz
- FMC controller to connect SDRAM, NOR and NAND memories
- QSPI
- SD/MMC/SDIO support
- 2*Ethernet controller
- CAN
- ADC/DAC
- USB EHCI/OHCI controllers
- USB OTG
- I2C, SPI, CAN busses support
- Several general purpose timers
- Serial Audio interface
- LCD controller
- DCMIPP
- SPDIFRX
- DFSDM

:Authors:

- Alexandre Torgue <alexandre.torgue@foss.st.com>


code:
===================
STM32MP157 Overview
===================

Introduction
------------

The STM32MP157 is a Cortex-A MPU aimed at various applications.
It features:

- Dual core Cortex-A7 application core
- 2D/3D image composition with GPU
- Standard memories interface support
- Standard connectivity, widely inherited from the STM32 MCU family
- Comprehensive security support

:Authors:

- Ludovic Barre <ludovic.barre@st.com>
- Gerald Baeza <gerald.baeza@st.com>


code:
==================
ARM Allwinner SoCs
==================

This document lists all the ARM Allwinner SoCs that are currently
supported in mainline by the Linux kernel. This document will also
provide links to documentation and/or datasheet for these SoCs.

SunXi family
------------
  Linux kernel mach directory: arch/arm/mach-sunxi

  Flavors:

    * ARM926 based SoCs
      - Allwinner F20 (sun3i)

        * Not Supported

    * ARM Cortex-A8 based SoCs
      - Allwinner A10 (sun4i)

        * Datasheet

	  http://dl.linux-sunxi.org/A10/A10%20Datasheet%20-%20v1.21%20%282012-04-06%29.pdf
	* User Manual

	  http://dl.linux-sunxi.org/A10/A10%20User%20Manual%20-%20v1.20%20%282012-04-09%2c%20DECRYPTED%29.pdf

      - Allwinner A10s (sun5i)

        * Datasheet

          http://dl.linux-sunxi.org/A10s/A10s%20Datasheet%20-%20v1.20%20%282012-03-27%29.pdf

      - Allwinner A13 / R8 (sun5i)

        * Datasheet

	  http://dl.linux-sunxi.org/A13/A13%20Datasheet%20-%20v1.12%20%282012-03-29%29.pdf
        * User Manual

          http://dl.linux-sunxi.org/A13/A13%20User%20Manual%20-%20v1.2%20%282013-01-08%29.pdf

      - Next Thing Co GR8 (sun5i)

    * Single ARM Cortex-A7 based SoCs
      - Allwinner V3s (sun8i)

        * Datasheet

          http://linux-sunxi.org/File:Allwinner_V3s_Datasheet_V1.0.pdf

    * Dual ARM Cortex-A7 based SoCs
      - Allwinner A20 (sun7i)

        * User Manual

          http://dl.linux-sunxi.org/A20/A20%20User%20Manual%202013-03-22.pdf

      - Allwinner A23 (sun8i)

        * Datasheet

          http://dl.linux-sunxi.org/A23/A23%20Datasheet%20V1.0%2020130830.pdf

        * User Manual

          http://dl.linux-sunxi.org/A23/A23%20User%20Manual%20V1.0%2020130830.pdf

    * Quad ARM Cortex-A7 based SoCs
      - Allwinner A31 (sun6i)

        * Datasheet

          http://dl.linux-sunxi.org/A31/A3x_release_document/A31/IC/A31%20datasheet%20V1.3%2020131106.pdf

        * User Manual

          http://dl.linux-sunxi.org/A31/A3x_release_document/A31/IC/A31%20user%20manual%20V1.1%2020130630.pdf

      - Allwinner A31s (sun6i)

        * Datasheet

          http://dl.linux-sunxi.org/A31/A3x_release_document/A31s/IC/A31s%20datasheet%20V1.3%2020131106.pdf

        * User Manual

          http://dl.linux-sunxi.org/A31/A3x_release_document/A31s/IC/A31s%20User%20Manual%20%20V1.0%2020130322.pdf

      - Allwinner A33 (sun8i)

        * Datasheet

          http://dl.linux-sunxi.org/A33/A33%20Datasheet%20release%201.1.pdf

        * User Manual

          http://dl.linux-sunxi.org/A33/A33%20user%20manual%20release%201.1.pdf

      - Allwinner H2+ (sun8i)

        * No document available now, but is known to be working properly with
          H3 drivers and memory map.

      - Allwinner H3 (sun8i)

        * Datasheet

          https://linux-sunxi.org/images/4/4b/Allwinner_H3_Datasheet_V1.2.pdf

      - Allwinner R40 (sun8i)

        * Datasheet

          https://github.com/tinalinux/docs/raw/r40-v1.y/R40_Datasheet_V1.0.pdf

        * User Manual

          https://github.com/tinalinux/docs/raw/r40-v1.y/Allwinner_R40_User_Manual_V1.0.pdf

    * Quad ARM Cortex-A15, Quad ARM Cortex-A7 based SoCs
      - Allwinner A80

        * Datasheet

	  http://dl.linux-sunxi.org/A80/A80_Datasheet_Revision_1.0_0404.pdf

    * Octa ARM Cortex-A7 based SoCs
      - Allwinner A83T

        * Datasheet

          https://github.com/allwinner-zh/documents/raw/master/A83T/A83T_Datasheet_v1.3_20150510.pdf

        * User Manual

          https://github.com/allwinner-zh/documents/raw/master/A83T/A83T_User_Manual_v1.5.1_20150513.pdf

    * Quad ARM Cortex-A53 based SoCs
      - Allwinner A64

        * Datasheet

          http://dl.linux-sunxi.org/A64/A64_Datasheet_V1.1.pdf

        * User Manual

          http://dl.linux-sunxi.org/A64/Allwinner%20A64%20User%20Manual%20v1.0.pdf

      - Allwinner H6

	* Datasheet

	  https://linux-sunxi.org/images/5/5c/Allwinner_H6_V200_Datasheet_V1.1.pdf

	* User Manual

	  https://linux-sunxi.org/images/4/46/Allwinner_H6_V200_User_Manual_V1.1.pdf

      - Allwinner H616

	* Datasheet

	  https://linux-sunxi.org/images/b/b9/H616_Datasheet_V1.0_cleaned.pdf

	* User Manual

	  https://linux-sunxi.org/images/2/24/H616_User_Manual_V1.0_cleaned.pdf


code:
=======================================================
Frequently asked questions about the sunxi clock system
=======================================================

This document contains useful bits of information that people tend to ask
about the sunxi clock system, as well as accompanying ASCII art when adequate.

Q: Why is the main 24MHz oscillator gatable? Wouldn't that break the
   system?

A: The 24MHz oscillator allows gating to save power. Indeed, if gated
   carelessly the system would stop functioning, but with the right
   steps, one can gate it and keep the system running. Consider this
   simplified suspend example:

   While the system is operational, you would see something like::

      24MHz         32kHz
       |
      PLL1
       \
        \_ CPU Mux
             |
           [CPU]

   When you are about to suspend, you switch the CPU Mux to the 32kHz
   oscillator::

      24Mhz         32kHz
       |              |
      PLL1            |
                     /
           CPU Mux _/
             |
           [CPU]

    Finally you can gate the main oscillator::

                    32kHz
                      |
                      |
                     /
           CPU Mux _/
             |
           [CPU]

Q: Were can I learn more about the sunxi clocks?

A: The linux-sunxi wiki contains a page documenting the clock registers,
   you can find it at

        http://linux-sunxi.org/A10/CCM

   The authoritative source for information at this time is the ccmu driver
   released by Allwinner, you can find it at

        https://github.com/linux-sunxi/linux-sunxi/tree/sunxi-3.0/arch/arm/mach-sun4i/clock/ccmu


code:
Software emulation of deprecated SWP instruction (CONFIG_SWP_EMULATE)
---------------------------------------------------------------------

ARMv6 architecture deprecates use of the SWP/SWPB instructions, and recommeds
moving to the load-locked/store-conditional instructions LDREX and STREX.

ARMv7 multiprocessing extensions introduce the ability to disable these
instructions, triggering an undefined instruction exception when executed.
Trapped instructions are emulated using an LDREX/STREX or LDREXB/STREXB
sequence. If a memory access fault (an abort) occurs, a segmentation fault is
signalled to the triggering process.

/proc/cpu/swp_emulation holds some statistics/information, including the PID of
the last process to trigger the emulation to be invocated. For example::

  Emulated SWP:		12
  Emulated SWPB:		0
  Aborted SWP{B}:		1
  Last process:		314

NOTE:
  when accessing uncached shared regions, LDREX/STREX rely on an external
  transaction monitoring block called a global monitor to maintain update
  atomicity. If your system does not implement a global monitor, this option can
  cause programs that perform SWP operations to uncached memory to deadlock, as
  the STREX operation will always fail.


code:
==================================================
ARM TCM (Tightly-Coupled Memory) handling in Linux
==================================================

Written by Linus Walleij <linus.walleij@stericsson.com>

Some ARM SoCs have a so-called TCM (Tightly-Coupled Memory).
This is usually just a few (4-64) KiB of RAM inside the ARM
processor.

Due to being embedded inside the CPU, the TCM has a
Harvard-architecture, so there is an ITCM (instruction TCM)
and a DTCM (data TCM). The DTCM can not contain any
instructions, but the ITCM can actually contain data.
The size of DTCM or ITCM is minimum 4KiB so the typical
minimum configuration is 4KiB ITCM and 4KiB DTCM.

ARM CPUs have special registers to read out status, physical
location and size of TCM memories. arch/arm/include/asm/cputype.h
defines a CPUID_TCM register that you can read out from the
system control coprocessor. Documentation from ARM can be found
at http://infocenter.arm.com, search for "TCM Status Register"
to see documents for all CPUs. Reading this register you can
determine if ITCM (bits 1-0) and/or DTCM (bit 17-16) is present
in the machine.

There is further a TCM region register (search for "TCM Region
Registers" at the ARM site) that can report and modify the location
size of TCM memories at runtime. This is used to read out and modify
TCM location and size. Notice that this is not a MMU table: you
actually move the physical location of the TCM around. At the
place you put it, it will mask any underlying RAM from the
CPU so it is usually wise not to overlap any physical RAM with
the TCM.

The TCM memory can then be remapped to another address again using
the MMU, but notice that the TCM is often used in situations where
the MMU is turned off. To avoid confusion the current Linux
implementation will map the TCM 1 to 1 from physical to virtual
memory in the location specified by the kernel. Currently Linux
will map ITCM to 0xfffe0000 and on, and DTCM to 0xfffe8000 and
on, supporting a maximum of 32KiB of ITCM and 32KiB of DTCM.

Newer versions of the region registers also support dividing these
TCMs in two separate banks, so for example an 8KiB ITCM is divided
into two 4KiB banks with its own control registers. The idea is to
be able to lock and hide one of the banks for use by the secure
world (TrustZone).

TCM is used for a few things:

- FIQ and other interrupt handlers that need deterministic
  timing and cannot wait for cache misses.

- Idle loops where all external RAM is set to self-refresh
  retention mode, so only on-chip RAM is accessible by
  the CPU and then we hang inside ITCM waiting for an
  interrupt.

- Other operations which implies shutting off or reconfiguring
  the external RAM controller.

There is an interface for using TCM on the ARM architecture
in <asm/tcm.h>. Using this interface it is possible to:

- Define the physical address and size of ITCM and DTCM.

- Tag functions to be compiled into ITCM.

- Tag data and constants to be allocated to DTCM and ITCM.

- Have the remaining TCM RAM added to a special
  allocation pool with gen_pool_create() and gen_pool_add()
  and provice tcm_alloc() and tcm_free() for this
  memory. Such a heap is great for things like saving
  device state when shutting off device power domains.

A machine that has TCM memory shall select HAVE_TCM from
arch/arm/Kconfig for itself. Code that needs to use TCM shall
#include <asm/tcm.h>

Functions to go into itcm can be tagged like this:
int __tcmfunc foo(int bar);

Since these are marked to become long_calls and you may want
to have functions called locally inside the TCM without
wasting space, there is also the __tcmlocalfunc prefix that
will make the call relative.

Variables to go into dtcm can be tagged like this::

  int __tcmdata foo;

Constants can be tagged like this::

  int __tcmconst foo;

To put assembler into TCM just use::

  .section ".tcm.text" or .section ".tcm.data"

respectively.

Example code::

  #include <asm/tcm.h>

  /* Uninitialized data */
  static u32 __tcmdata tcmvar;
  /* Initialized data */
  static u32 __tcmdata tcmassigned = 0x2BADBABEU;
  /* Constant */
  static const u32 __tcmconst tcmconst = 0xCAFEBABEU;

  static void __tcmlocalfunc tcm_to_tcm(void)
  {
	int i;
	for (i = 0; i < 100; i++)
		tcmvar ++;
  }

  static void __tcmfunc hello_tcm(void)
  {
	/* Some abstract code that runs in ITCM */
	int i;
	for (i = 0; i < 100; i++) {
		tcmvar ++;
	}
	tcm_to_tcm();
  }

  static void __init test_tcm(void)
  {
	u32 *tcmem;
	int i;

	hello_tcm();
	printk("Hello TCM executed from ITCM RAM\n");

	printk("TCM variable from testrun: %u @ %p\n", tcmvar, &tcmvar);
	tcmvar = 0xDEADBEEFU;
	printk("TCM variable: 0x%x @ %p\n", tcmvar, &tcmvar);

	printk("TCM assigned variable: 0x%x @ %p\n", tcmassigned, &tcmassigned);

	printk("TCM constant: 0x%x @ %p\n", tcmconst, &tcmconst);

	/* Allocate some TCM memory from the pool */
	tcmem = tcm_alloc(20);
	if (tcmem) {
		printk("TCM Allocated 20 bytes of TCM @ %p\n", tcmem);
		tcmem[0] = 0xDEADBEEFU;
		tcmem[1] = 0x2BADBABEU;
		tcmem[2] = 0xCAFEBABEU;
		tcmem[3] = 0xDEADBEEFU;
		tcmem[4] = 0x2BADBABEU;
		for (i = 0; i < 5; i++)
			printk("TCM tcmem[%d] = %08x\n", i, tcmem[i]);
		tcm_free(tcmem, 20);
	}
  }


code:
================================================
The Unified Extensible Firmware Interface (UEFI)
================================================

UEFI, the Unified Extensible Firmware Interface, is a specification
governing the behaviours of compatible firmware interfaces. It is
maintained by the UEFI Forum - http://www.uefi.org/.

UEFI is an evolution of its predecessor 'EFI', so the terms EFI and
UEFI are used somewhat interchangeably in this document and associated
source code. As a rule, anything new uses 'UEFI', whereas 'EFI' refers
to legacy code or specifications.

UEFI support in Linux
=====================
Booting on a platform with firmware compliant with the UEFI specification
makes it possible for the kernel to support additional features:

- UEFI Runtime Services
- Retrieving various configuration information through the standardised
  interface of UEFI configuration tables. (ACPI, SMBIOS, ...)

For actually enabling [U]EFI support, enable:

- CONFIG_EFI=y
- CONFIG_EFIVAR_FS=y or m

The implementation depends on receiving information about the UEFI environment
in a Flattened Device Tree (FDT) - so is only available with CONFIG_OF.

UEFI stub
=========
The "stub" is a feature that extends the Image/zImage into a valid UEFI
PE/COFF executable, including a loader application that makes it possible to
load the kernel directly from the UEFI shell, boot menu, or one of the
lightweight bootloaders like Gummiboot or rEFInd.

The kernel image built with stub support remains a valid kernel image for
booting in non-UEFI environments.

UEFI kernel support on ARM
==========================
UEFI kernel support on the ARM architectures (arm and arm64) is only available
when boot is performed through the stub.

When booting in UEFI mode, the stub deletes any memory nodes from a provided DT.
Instead, the kernel reads the UEFI memory map.

The stub populates the FDT /chosen node with (and the kernel scans for) the
following parameters:

==========================  ======   ===========================================
Name                        Size     Description
==========================  ======   ===========================================
linux,uefi-system-table     64-bit   Physical address of the UEFI System Table.

linux,uefi-mmap-start       64-bit   Physical address of the UEFI memory map,
                                     populated by the UEFI GetMemoryMap() call.

linux,uefi-mmap-size        32-bit   Size in bytes of the UEFI memory map
                                     pointed to in previous entry.

linux,uefi-mmap-desc-size   32-bit   Size in bytes of each entry in the UEFI
                                     memory map.

linux,uefi-mmap-desc-ver    32-bit   Version of the mmap descriptor format.

kaslr-seed                  64-bit   Entropy used to randomize the kernel image
                                     base address location.
==========================  ======   ===========================================


code:
===============================================
Release notes for Linux Kernel VFP support code
===============================================

Date: 	20 May 2004

Author:	Russell King

This is the first release of the Linux Kernel VFP support code.  It
provides support for the exceptions bounced from VFP hardware found
on ARM926EJ-S.

This release has been validated against the SoftFloat-2b library by
John R. Hauser using the TestFloat-2a test suite.  Details of this
library and test suite can be found at:

   http://www.jhauser.us/arithmetic/SoftFloat.html

The operations which have been tested with this package are:

 - fdiv
 - fsub
 - fadd
 - fmul
 - fcmp
 - fcmpe
 - fcvtd
 - fcvts
 - fsito
 - ftosi
 - fsqrt

All the above pass softfloat tests with the following exceptions:

- fadd/fsub shows some differences in the handling of +0 / -0 results
  when input operands differ in signs.
- the handling of underflow exceptions is slightly different.  If a
  result underflows before rounding, but becomes a normalised number
  after rounding, we do not signal an underflow exception.

Other operations which have been tested by basic assembly-only tests
are:

 - fcpy
 - fabs
 - fneg
 - ftoui
 - ftosiz
 - ftouiz

The combination operations have not been tested:

 - fmac
 - fnmac
 - fmsc
 - fnmsc
 - fnmul