View source for Arch directory restructuring

The ''arch'' directory is a mess with lots of copy-pasted code. Let's fix that!

== Some definitions ==

Common sense suggests the following taxonomy of parts for MCU-equipped devices targeted by Miosix:
* Board: The device itself being targeted. It's called a board because nobody has observed any MCU wired with point-to-point wiring yet. Includes the MCU itself plus any peripheral external to the MCU but '''driven''' by it.
* Chip: The MCU itself. May come in RAM/OTP/ROM/Flash size variations, which are mostly ignored.
* Chip family: A set of MCU types from the same manufacturer with the same microprocessor core but potentially different set of peripherals. While the available set of peripherals may vary, the behaviour and I/O ports of each kind of peripheral are the same across the entire family. Thanks to the brilliant ideas of the various marketing departments of each vendor, the classification here can get very fluid.
* Core: The microprocessor core used by a given chip family.

Let's take as an example the classic stm32f4discovery board that is the most common development device for Miosix:
* The board is the stm32f4discovery itself. It includes the chip, and miscellaneous peripherals such as an accelerometer and a Cirrus Logic audio chip. The STLink programming interface and the power supply are '''not''' considered relevant parts of the board for Miosix, as the MCU is not in control of what they do.
* The chip is an STM32F407VGT6. The VGT6 suffix of the chip name specifies package (100 pin LQFP), Flash size (1MB) and temperature range options (see the datasheet at the "Ordering Information" page).
* The chip family is STM32F4. This can be inferred by the fact that all available chips with this prefix in the part name share the same reference manual.
* The core is an ARM Cortex M4, as stated in the datasheet. Roughly, ST buys the Verilog for the core from ARM and then takes care of the manufacturing. As far as we know, ARM's licence shouldn't allow ST to customize the core in any way, so all Cortex M4 cores should behave the same, even from other vendors.

One definition we did not give is the definition of what an '''architecture''' is. The reason is that there is no accepted definition for this term, especially for forum pundits and bloggers, but also in academia. The RISC school of thought (Patterson/Hennessy and their spawn) historically associated an ''architecture'' with a combination of what are more specifically called the ''instruction set architecture'' (ISA) and the ''microarchitecture'' of a core. Their thesis was that the microarchitecture design will follow naturally from the definition of the ISA, hence simpler ISAs (RISC) to implement always lead to more efficient and generally better cores. However the industry has proven them wrong, and the most glaring example are Intel x86 chips, which have seen an increasing variety of microarchitectures implementing the same ISA (variously extended of course) with wildly varying levels of (non-)efficiency (in all possible ramifications of "efficiency"). Closer to Miosix's targets, the ARM ISA has been extended so much over the years that its core RISC design has now evolved to basically a traditional CISC ISA, but ARM chips still come in every possible size and flavour. Usually we talk about x86 "architectures" or ARM "architectures", but do we mean desktop-grade chips or microcontrollers? Even though they have the same "architecture" the cores in these two classes of chips have nothing to do with each other, they don't even share the same instruction decoder probably. Hence our conclusion that the word "architecture" has now lost all useful meaning for our purposes, and is only useful for void parlor chitchat.

And then we come to Miosix which defines "architecture" (arch) as... a board. Which is not what anyone means when they talk about architecture of anything. For Miosix, an "architecture" is more like what in common parlance would be meant as a "platform".

== Current structure ==

<pre>
arch                        
  common                      Pool of useful files. Very few files here are common to all archs.
    CMSIS                       Collection of ARM & vendor headers following the CMSIS standard
    core                        Board independent drivers required for the OS to function (roughly)
      atomic_ops_*.h              Core dependent
      cache_*.cpp/h               Core dependent. This is not required at all for Miosix to work but is nevertheless here
      *_os_timer.cpp              Chip family dependent
      endianness_*.h              Core dependent. Should have a generic (slow) implementation but it's missing.
      interrupts.h                Umbrella header for interrupts_*.h
      interrupts_*.h              Core dependent. Misleading name, this is for fault handling.
      memory_protection.h         Umbrella header for mpu_*.h. Required only for process mode. Name is not consistent with other umbrella headers, should have been "mpu.h"
      mpu_*.cpp/h                 Core dependent.
    drivers                     Miscellaneous drivers, which are "common" only very roughly
      dcc.cpp/h                   Core dependent (but common to all ARM cores apparently)
      *_adc.cpp/h                 Chip family dependent
      serial.h                    Umbrella header for *serial*.h
      *serial*.cpp/h              Chip family dependent
      sd_*.cpp/h                  Chip family dependent
      servo_*.cpp/h               Board dependent really, should go into utils
      *_hardware_rng.cpp/h        Chip family dependent
      *_rtc.cpp/h                 Chip family dependent
      *_sgm.cpp/h                 Chip family dependent
      *_wd.cpp/h                  Chip family dependent
      *_i2c.cpp/h                 Chip family dependent
  <board group name>          Board specific files.Board names are decided based on chip family but also include the core in their name
    common                      Common drivers and configuration for all the boards in the group
      arch_settings.h             Core dependent. Misleading name, defines requirements for ctxsave
      interfaces-impl             The actual drivers
        arch_registers_impl.h     Chip family dependent. Includes the appropriate register definitions
        delays.cpp                Chip family dependent as it also depends on ROM/Flash speed. Actually application dependent (!) as cache/prefetch mechanisms can be configured but whatever.
        gpio_impl.cpp/h           Chip family dependent.
        portability_impl.h        Core dependent.
        portability.cpp           Core dependent.
    <board name>              Board/chip specific files.
      core                      Board/chip dependent code required for the OS to function.
        stage_1_boot.c/cpp/s      Chip dependent. Interrupt vector table, reset handler, clock tree setup, bss/data initialization
      interfaces_impl         Board/chip specific drivers.
        bsp_impl.h              Board dependent. Useful board-specific definitions.
        bsp.cpp                 Board dependent. Useful board-specific functions.
        hwmapping.h             Board dependent. GPIO pin definitions.
        delays.cpp              See above. Sometimes it's here, with no true reason why.
        arch_registers_impl.h     See above. Sometimes it's here, depends on chip.
        ...                     Some boards have extra miscellaneous drivers here
interfaces                 
</pre>

''<board group name>'' is defined as the name of the chip core, followed by an underscore, followed by the name of a chip family. ''<board name>'' is defined by the name of the chip, followed by an underscore, followed by a "common name" of the board. For commercial prototyping boards or specific devices, "common name" is derived from the name given by the manufacturer, or a name which is in common use with some exceptions (i.e. stm32f103 bluepill boards are named "breakout").

Some general patterns can be inferred:
* Apart from minor exceptions, directories named '''core''' contain drivers required for the OS to function.
* Directories named '''interfaces_impl''' generally contain implementations of things defined in /interfaces. Header files in '''interfaces_impl''' are always given the ``_impl`` suffix. C++ files are usually not given the "_impl" suffix but sometimes they have it (gpio_impl.cpp).
* Directories named '''common''' contain code shared by multiple boards. No attempt is made to separate different levels of commonality apart from chip-family specific stuff which is grouped by board group.

=== Issues ===

Experience has shown this organization has the following problems:
* What goes where is not well defined due to the vagueness of directory names, which leads to files being in the wrong place even though it's not obvious
** servo_* is the most glaring example
** The location of delays.cpp and arch_registers_impl.h is also inconsistent
* The two level board group/board classification does not reflect reality, which leads to missing code sharing opportunities:
** GPIO implementations are duplicated multiple times as they are common to multiple chip families and not to a single one.
** Bootstrap code is duplicated multiple times as they are common to boards with the same chip and not common to the board.
** Portability code (i.e. context save/restore primitives mostly) is duplicated multiple times as they are common to a given core and not to a chip family