Arch directory restructuring - Revision history

Daniele.cattaneo: More details that were missing

2024-10-23T00:12:45Z

More details that were missing

← Older revision		Revision as of 00:12, 23 October 2024
Line 7:		Line 7:

	Common sense suggests the following taxonomy of parts for MCU-equipped devices targeted by Miosix:		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.		* Board: The device itself being targeted. It's called a board because nobody has observed any MCU wired with point-to-point wiring yet (citation needed). 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: 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.		* 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.
Line 15:		Line 15:
	* 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 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 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 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. (Notice that this is a slight simplification of reality because there are STM32F4 chips that are not covered by the same reference manual as the STM32F407 but the point we want to get across is that multiple MCUs share roughly the same silicon behaviour and drivers)
	* 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.		* 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 only allows ST to customize the core in very limited ways, so all Cortex M4 cores should behave basically the same, even from other vendors. Tunables may be things like the number of MPU regions or whether floating point is available or not, which may be important or not.

	=== What is an architecture? ===		=== What is an architecture? ===

Daniele.cattaneo at 17:29, 31 December 2023

2023-12-31T17:29:36Z

← Older revision		Revision as of 17:29, 31 December 2023
Line 1:		Line 1:
	The ''arch'' directory is a mess with lots of copy-pasted code. Ideally it should be '''consistently and logically organized''': each directory should have a documented purpose in order to leave as little doubt as possible about ''what goes where''. Additionally, each directory's purpose makes sense in the overall structure, without overlaps between the scope of each directory.		The ''arch'' directory is a mess with lots of copy-pasted code. Ideally it should be '''consistently and logically organized''': each directory should have a documented purpose in order to leave as little doubt as possible about ''what goes where''. Additionally, each directory's purpose makes sense in the overall structure, without overlaps between the scope of each directory.
	At the moment however we observe this is not the case. We believe that in order to make the future growth of Miosix simpler and faster, the right moment to rectify the situation is now.		At the moment however we observe this is not the case. We believe that in order to make the future growth of Miosix simpler and faster, the right moment to rectify the situation is now.

			''Update 31/12/2023'' I discovered a bug in the testing branch of Miosix which was caused by the copy-pasting of gpio_impl.h: version 1.4 (sic, see comments) didn't have the alternateFunction method of Gpio, even though serial_stm32.cpp assumes it always exists. (btw don't we have git? manual versioning in comments is not a robust practice!!!) I bet other similar bugs exist.

	== Some definitions ==		== Some definitions ==

Daniele.cattaneo at 23:14, 17 November 2023

2023-11-17T23:14:43Z

← Older revision		Revision as of 23:14, 17 November 2023
Line 147:		Line 147:

	Notice that, despite the name of the defines, there is no distinction between include paths and source paths, as includes are alongside the source. We do not have a problem with this approach, however it results in all includes being publicly available for applications, which is something that is not entirely desirable.		Notice that, despite the name of the defines, there is no distinction between include paths and source paths, as includes are alongside the source. We do not have a problem with this approach, however it results in all includes being publicly available for applications, which is something that is not entirely desirable.

			==== Drivers selected by include path ====

			Sometimes Miosix's headers include files that depend on the board selected for building. This of course can give problems when reorganizing files around. The affected files are:

			* interfaces/arch_registers.h
			* interfaces/bsp.h
			* interfaces/gpio.h
			* interfaces/portability.h

			Overall selecting different files through the include paths is desirable, so we want to avoid adding additional architecture-specific ifdefs as much as possible.

	=== Issues ===		=== Issues ===
Line 159:		Line 170:
	** Bootstrap code is duplicated multiple times as they are common to boards with the same chip and not common to the board.		** 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		** 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
			** Linker scripts are also duplicated multiple times
	* Classifications sometimes privilege syntax rather than semantics, in an inconsistent fashion		* Classifications sometimes privilege syntax rather than semantics, in an inconsistent fashion
	** Directories named '''interfaces_impl''' contain drivers just like directories named '''drivers''', except that they included from /interfaces.		** Directories named '''interfaces_impl''' contain drivers just like directories named '''drivers''', except that they included from /interfaces.
Line 169:		Line 181:
	== A proposal ==		== A proposal ==

	Pointing out what's wrong is easy, fixing it up is hard. Of course "what we should do" is a matter of opinion, and a valid answer to that could even be "nothing". ~~If I were~~ to ~~do something~~, ~~I would do the following:~~		Pointing out what's wrong is easy, fixing it up is hard. Of course "what we should do" is a matter of opinion, and a valid answer to that could even be "nothing". Overall, what we ultimately want is for all drivers to be decoupled from boards and board groups, in order to be able to classify each driver depending on its actual logical group it belongs to. We can take this opportunity for a more radical restructuring of Miosix's source tree, or we can opt for more conservative solutions.

	=== With classification per device type ===		=== With classification per device type ===

			This proposal is the most radical as it splits the drivers in a completely different way than what is currently done: by device type. For instance all USART drivers go in a "serial" directory, all GPIO drivers go in a GPIO directory, and so on. This approach scales well when there are a lot of drivers around, but completely prevents selection of drivers by using the include paths.

			The arch directory has been named "platform" because of our general dislike of the "architecture" word, but that's really just a bonus. Most other operating systems use "arch" as a directory for drivers and target-specific stuff, so keeping the name "arch" is also an option. We also moved the interfaces headers under the "platform" ("arch") directory, since they basically are just umbrella headers for various drivers. This loses the distinction of some of them being more essential than others, additional directories can be added for this purpose.

	<pre>		<pre>
Line 265:		Line 281:

	=== Without classification per device type ===		=== Without classification per device type ===

			This is just the same proposal as before but which classifies drivers only by "manufacturer" or chip. This allows to use the include trick for selecting headers.

	<pre>		<pre>

Daniele.cattaneo at 09:13, 16 November 2023

2023-11-16T09:13:19Z

@@ Line 95: / Line 95: @@
    utils.cpp/h                 Memory/CPU usage profiling. Misleading name. Not a driver
    ...                         Other files are not related to hardware
 </pre>
@@ Line 103: / Line 110: @@
 * 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 ===
@@ Line 213: / Line 257: @@
      <chip>
        *.ld
 </pre>
@@ Line 279: / Line 328: @@
      <chip>
        *.ld
 </pre>

Daniele.cattaneo: Start of proposal

2023-11-13T15:44:25Z

Start of proposal

Show changes

Daniele.cattaneo: More

2023-11-13T14:47:44Z

Show changes

Daniele.cattaneo at 13:24, 13 November 2023

2023-11-13T13:24:04Z

← Older revision		Revision as of 13:24, 13 November 2023
Line 27:		Line 27:
	core Board independent drivers required for the OS to function (roughly)		core Board independent drivers required for the OS to function (roughly)
	atomic_ops_*.h Core dependent		atomic_ops_*.h Core dependent
	cache_*.cpp/h Core dependent. This is not required for Miosix but is nevertheless here		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		*_os_timer.cpp Chip family dependent
	endianness_*.h Core dependent. Should have a generic (slow) implementation.		endianness_*.h Core dependent. Should have a generic (slow) implementation but it's missing.
	interrupts.h Umbrella header for interrupts_*.h		interrupts.h Umbrella header for interrupts_*.h
	interrupts_*.h Core dependent. Misleading name, this is for fault handling.		interrupts_*.h Core dependent. Misleading name, this is for fault handling.
	memory_protection.h Umbrella header for mpu_*.h. Required only for process mode.		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.		mpu_*.cpp/h Core dependent.
	drivers Miscellaneous drivers, which are "common" only very roughly		drivers Miscellaneous drivers, which are "common" only very roughly

Daniele.cattaneo: Fix lists once again

2023-11-13T13:17:39Z

Fix lists once again

← Older revision		Revision as of 13:17, 13 November 2023
Line 79:		Line 79:
	Experience has shown this organization has the following problems:		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		* 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		** servo_* is the most glaring example
	* The location of delays.cpp and arch_registers_impl.h is also inconsistent		** 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:		* 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.		** 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.		** 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		** 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

Daniele.cattaneo: Fix lists

2023-11-13T13:16:47Z

Fix lists

Daniele.cattaneo: Start writing

2023-11-13T13:16:08Z

Start writing

New page

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 for Miosix but is nevertheless here
*_os_timer.cpp Chip family dependent
endianness_*.h Core dependent. Should have a generic (slow) implementation.
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.
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

← Older revision		Revision as of 13:16, 13 November 2023
Line 4:		Line 4:

	Common sense suggests the following taxonomy of parts for MCU-equipped devices targeted by Miosix:		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.		* 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: 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.		* 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.		* 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:		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 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 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 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.		* 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.		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.
Line 71:		Line 71:

	Some general patterns can be inferred:		Some general patterns can be inferred:
	* Apart from minor exceptions, directories named '''core''' contain drivers required for the OS to function.		* 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 '''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.		* 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 ===		=== Issues ===

	Experience has shown this organization has the following problems:		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		* 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		* servo_* is the most glaring example
	* The location of delays.cpp and arch_registers_impl.h is also inconsistent		* 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:		* 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.		* 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.		* 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		* 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