arch: remove frv port

	- information about the FMC bus abstraction

fpga/

	- FPGA Manager Core.

frv/

	- Fujitsu FR-V Linux documentation.

futex-requeue-pi.txt

	- info on requeueing of tasks from a non-PI futex to a PI futex

gcc-plugins.txt

		       ================================

		       Fujitsu FR-V LINUX DOCUMENTATION

		       ================================

This directory contains documentation for the Fujitsu FR-V CPU architecture

port of Linux.

The following documents are available:

 (*) features.txt

     A description of the basic features inherent in this architecture port.

 (*) configuring.txt

     A summary of the configuration options particular to this architecture.

 (*) booting.txt

     A description of how to boot the kernel image and a summary of the kernel

     command line options.

 (*) gdbstub.txt

     A description of how to debug the kernel using GDB attached by serial

     port, and a summary of the services available.

 (*) mmu-layout.txt

     A description of the virtual and physical memory layout used in the

     MMU linux kernel, and the registers used to support it.

 (*) gdbinit

     An example .gdbinit file for use with GDB. It includes macros for viewing

     MMU state on the FR451. See mmu-layout.txt for more information.

 (*) clock.txt

     A description of the CPU clock scaling interface.

 (*) atomic-ops.txt

     A description of how the FR-V kernel's atomic operations work.

			       =====================================

			       FUJITSU FR-V KERNEL ATOMIC OPERATIONS

			       =====================================

On the FR-V CPUs, there is only one atomic Read-Modify-Write operation: the SWAP/SWAPI

instruction. Unfortunately, this alone can't be used to implement the following operations:

 (*) Atomic add to memory

 (*) Atomic subtract from memory

 (*) Atomic bit modification (set, clear or invert)

 (*) Atomic compare and exchange

On such CPUs, the standard way of emulating such operations in uniprocessor mode is to disable

interrupts, but on the FR-V CPUs, modifying the PSR takes a lot of clock cycles, and it has to be

done twice. This means the CPU runs for a relatively long time with interrupts disabled,

potentially having a great effect on interrupt latency.

=============

NEW ALGORITHM

=============

To get around this, the following algorithm has been implemented. It operates in a way similar to

the LL/SC instruction pairs supported on a number of platforms.

 (*) The CCCR.CC3 register is reserved within the kernel to act as an atomic modify abort flag.

 (*) In the exception prologues run on kernel->kernel entry, CCCR.CC3 is set to 0 (Undefined

     state).

 (*) All atomic operations can then be broken down into the following algorithm:

     (1) Set ICC3.Z to true and set CC3 to True (ORCC/CKEQ/ORCR).

     (2) Load the value currently in the memory to be modified into a register.

     (3) Make changes to the value.

     (4) If CC3 is still True, simultaneously and atomically (by VLIW packing):

	 (a) Store the modified value back to memory.

	 (b) Set ICC3.Z to false (CORCC on GR29 is sufficient for this - GR29 holds the current

	     task pointer in the kernel, and so is guaranteed to be non-zero).

     (5) If ICC3.Z is still true, go back to step (1).

This works in a non-SMP environment because any interrupt or other exception that happens between

steps (1) and (4) will set CC3 to the Undefined, thus aborting the store in (4a), and causing the

condition in ICC3 to remain with the Z flag set, thus causing step (5) to loop back to step (1).

This algorithm suffers from two problems:

 (1) The condition CCCR.CC3 is cleared unconditionally by an exception, irrespective of whether or

     not any changes were made to the target memory location during that exception.

 (2) The branch from step (5) back to step (1) may have to happen more than once until the store

     manages to take place. In theory, this loop could cycle forever because there are too many

     interrupts coming in, but it's unlikely.

=======

EXAMPLE

=======

Taking an example from include/asm-frv/atomic.h:

	static inline int atomic_add_return(int i, atomic_t *v)

	{

		unsigned long val;

		asm("0:						\n"

It starts by setting ICC3.Z to true for later use, and also transforming that into CC3 being in the

True state.

		    "	orcc		gr0,gr0,gr0,icc3	\n"	<-- (1)

		    "	ckeq		icc3,cc7		\n"	<-- (1)

Then it does the load. Note that the final phase of step (1) is done at the same time as the

load. The VLIW packing ensures they are done simultaneously. The ".p" on the load must not be

removed without swapping the order of these two instructions.

		    "	ld.p		%M0,%1			\n"	<-- (2)

		    "	orcr		cc7,cc7,cc3		\n"	<-- (1)

Then the proposed modification is generated. Note that the old value can be retained if required

(such as in test_and_set_bit()).

		    "	add%I2		%1,%2,%1		\n"	<-- (3)

Then it attempts to store the value back, contingent on no exception having cleared CC3 since it

was set to True.

		    "	cst.p		%1,%M0		,cc3,#1	\n"	<-- (4a)

It simultaneously records the success or failure of the store in ICC3.Z.

		    "	corcc		gr29,gr29,gr0	,cc3,#1	\n"	<-- (4b)

Such that the branch can then be taken if the operation was aborted.

		    "	beq		icc3,#0,0b		\n"	<-- (5)

		    : "+U"(v->counter), "=&r"(val)

		    : "NPr"(i)

		    : "memory", "cc7", "cc3", "icc3"

		    );

		return val;

	}

=============

CONFIGURATION

=============

The atomic ops implementation can be made inline or out-of-line by changing the

CONFIG_FRV_OUTOFLINE_ATOMIC_OPS configuration variable. Making it out-of-line has a number of

advantages:

 - The resulting kernel image may be smaller

 - Debugging is easier as atomic ops can just be stepped over and they can be breakpointed

Keeping it inline also has a number of advantages:

 - The resulting kernel may be Faster

   - no out-of-line function calls need to be made

   - the compiler doesn't have half its registers clobbered by making a call

The out-of-line implementations live in arch/frv/lib/atomic-ops.S.

			  =========================

			  BOOTING FR-V LINUX KERNEL

			  =========================

======================

PROVIDING A FILESYSTEM

======================

First of all, a root filesystem must be made available. This can be done in

one of two ways:

  (1) NFS Export

      A filesystem should be constructed in a directory on an NFS server that

      the target board can reach. This directory should then be NFS exported

      such that the target board can read and write into it as root.

  (2) Flash Filesystem (JFFS2 Recommended)

      In this case, the image must be stored or built up on flash before it

      can be used. A complete image can be built using the mkfs.jffs2 or

      similar program and then downloaded and stored into flash by RedBoot.

========================

LOADING THE KERNEL IMAGE

========================

The kernel will need to be loaded into RAM by RedBoot (or by some alternative

boot loader) before it can be run. The kernel image (arch/frv/boot/Image) may

be loaded in one of three ways:

  (1) Load from Flash

      This is the simplest. RedBoot can store an image in the flash (see the

      RedBoot documentation) and then load it back into RAM. RedBoot keeps

      track of the load address, entry point and size, so the command to do

      this is simply:

	fis load linux

      The image is then ready to be executed.

  (2) Load by TFTP

      The following command will download a raw binary kernel image from the

      default server (as negotiated by BOOTP) and store it into RAM:

	load -b 0x00100000 -r /tftpboot/image.bin

      The image is then ready to be executed.

  (3) Load by Y-Modem

      The following command will download a raw binary kernel image across the

      serial port that RedBoot is currently using:

	load -m ymodem -b 0x00100000 -r zImage

      The serial client (such as minicom) must then be told to transmit the

      program by Y-Modem.

      When finished, the image will then be ready to be executed.

==================

BOOTING THE KERNEL

==================

Boot the image with the following RedBoot command:

	exec -c "<CMDLINE>" 0x00100000

For example:

	exec -c "console=ttySM0,115200 ip=:::::dhcp root=/dev/mtdblock2 rw"

This will start the kernel running. Note that if the GDB-stub is compiled in,

then the kernel will immediately wait for GDB to connect over serial before

doing anything else. See the section on kernel debugging with GDB.

The kernel command line <CMDLINE> tells the kernel where its console is and

how to find its root filesystem. This is made up of the following components,

separated by spaces:

  (*) console=ttyS<x>[,<baud>[<parity>[<bits>[<flow>]]]]

      This specifies that the system console should output through on-chip

      serial port <x> (which can be "0" or "1").

      <baud> is a standard baud rate between 1200 and 115200 (default 9600).

      <parity> is a parity setting of "N", "O", "E", "M" or "S" for None, Odd,

      Even, Mark or Space. "None" is the default.

      <stop> is "7" or "8" for the number of bits per character. "8" is the

      default.

      <flow> is "r" to use flow control (XCTS on serial port 2 only). The

      default is to not use flow control.

      For example:

	console=ttyS0,115200

      To use the first on-chip serial port at baud rate 115200, no parity, 8

      bits, and no flow control.

  (*) root=<xxxx>

      This specifies the device upon which the root filesystem resides. It

      may be specified by major and minor number, device path, or even

      partition uuid, if supported.  For example:

	/dev/nfs	NFS root filesystem

	/dev/mtdblock3	Fourth RedBoot partition on the System Flash

	PARTUUID=00112233-4455-6677-8899-AABBCCDDEEFF/PARTNROFF=1

		first partition after the partition with the given UUID

	253:0		Device with major 253 and minor 0

      Authoritative information can be found in

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

  (*) rw

      Start with the root filesystem mounted Read/Write.

  The remaining components are all optional:

  (*) ip=<ip>::::<host>:<iface>:<cfg>

      Configure the network interface. If <cfg> is "off" then <ip> should

      specify the IP address for the network device <iface>. <host> provide

      the hostname for the device.

      If <cfg> is "bootp" or "dhcp", then all of these parameters will be

      discovered by consulting a BOOTP or DHCP server.

      For example, the following might be used:

	ip=192.168.73.12::::frv:eth0:off

      This sets the IP address on the VDK motherboard RTL8029 ethernet chipset

      (eth0) to be 192.168.73.12, and sets the board's hostname to be "frv".

  (*) nfsroot=<server>:<dir>[,v<vers>]

      This is mandatory if "root=/dev/nfs" is given as an option. It tells the

      kernel the IP address of the NFS server providing its root filesystem,

      and the pathname on that server of the filesystem.

      The NFS version to use can also be specified. v2 and v3 are supported by

      Linux.

      For example:

	nfsroot=192.168.73.1:/nfsroot-frv

  (*) profile=1

      Turns on the kernel profiler (accessible through /proc/profile).

  (*) console=gdb0

      This can be used as an alternative to the "console=ttyS..." listed

      above. I tells the kernel to pass the console output to GDB if the

      gdbstub is compiled in to the kernel.

      If this is used, then the gdbstub passes the text to GDB, which then

      simply dumps it to its standard output.

  (*) mem=<xxx>M

      Normally the kernel will work out how much SDRAM it has by reading the

      SDRAM controller registers. That can be overridden with this

      option. This allows the kernel to be told that it has <xxx> megabytes of

      memory available.

  (*) init=<prog> [<arg> [<arg> [<arg> ...]]]

      This tells the kernel what program to run initially. By default this is

      /sbin/init, but /sbin/sash or /bin/sh are common alternatives.

Clock scaling

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

The kernel supports scaling of CLCK.CMODE, CLCK.CM and CLKC.P0 clock

registers. If built with CONFIG_PM and CONFIG_SYSCTL options enabled, four

extra files will appear in the directory /proc/sys/pm/. Reading these files

will show:

      p0		-- current value of the P0 bit in CLKC register.

      cm		-- current value of the CM bits in CLKC register.

      cmode		-- current value of the CMODE bits in CLKC register.

On all boards, the 'p0' file should also be writable, and either '1' or '0'

can be rewritten, to set or clear the CLKC_P0 bit respectively, hence

controlling whether the resource bus rate clock is halved.

The 'cm' file should also be available on all boards. '0' can be written to it

to shift the board into High-Speed mode (normal), and '1' can be written to

shift the board into Medium-Speed mode. Selecting Low-Speed mode is not

supported by this interface, even though some CPUs do support it.

On the boards with FR405 CPU (i.e. CB60 and CB70), the 'cmode' file is also

writable, allowing the CPU core speed (and other clock speeds) to be

controlled from userspace.

Determining current and possible settings

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

The current state and the available masks can be found in /proc/cpuinfo. For

example, on the CB70:

	# cat /proc/cpuinfo

	CPU-Series:     fr400

	CPU-Core:       fr405, gr0-31, BE, CCCR

	CPU:            mb93405

	MMU:            Prot

	FP-Media:       fr0-31, Media

	System:         mb93091-cb70, mb93090-mb00

	PM-Controls:    cmode=0xd31f, cm=0x3, p0=0x3, suspend=0x9

	PM-Status:      cmode=3, cm=0, p0=0

	Clock-In:       50.00 MHz

	Clock-Core:     300.00 MHz

	Clock-SDRAM:    100.00 MHz

	Clock-CBus:     100.00 MHz

	Clock-Res:      50.00 MHz

	Clock-Ext:      50.00 MHz

	Clock-DSU:      25.00 MHz

	BogoMips:       300.00

And on the PDK, the PM lines look like the following:

	PM-Controls:    cm=0x3, p0=0x3, suspend=0x9

	PM-Status:      cmode=9, cm=0, p0=0

The PM-Controls line, if present, will indicate which /proc/sys/pm files can

be set to what values. The specification values are bitmasks; so, for example,

"suspend=0x9" indicates that 0 and 3 can be written validly to

/proc/sys/pm/suspend.

The PM-Controls line will only be present if CONFIG_PM is configured to Y.

The PM-Status line indicates which clock controls are set to which value. If

the file can be read, then the suspend value must be 0, and so that's not

included.