Readme to describe the purpose, structure and contents of the HDL libraries directory.

libraries/readme_libraries.txt

+
+The libraries directory contains the HDL libraries that are reused by the HDL designs.
+
+  libraries/-- Technology independent components
+            base/         -- common, diag, diagnostics, dp, mm, sens, tst, uth, ...
+            dsp/
+            external/     -- easics, numonyx_m25p128
+            io/           -- epcs, i2c, ppsh, remu, ...
+            
+            -- Mapping to technology dependent vendor IP components
+            technology
+
+The technology directory provides the FPGA specific IP as technology independent IP.
+
+  technology/-- FPGA chip vendor IP
+             altera/
+                    altera_mf       -- general Altera FPGA IP
+                    stratixiv       -- Stratix IV specific IP
+                    stratixiv_hssi  -- Stratix IV High Speed Serial Interface transceiver IP
+             xilinx/
+             
+             -- Technology packages
+             base/technology_pkg.vhd         -- technology identifiers and some low level functions
+                  technology_select_pkg.vhd  -- constant for default device selection 
+             
+             -- Technology independent IP
+             fifo/         -- FIFOs
+             flash/        -- access to external flash memory
+             iobuf/        -- simple PHY IO pin buffers
+             memory/       -- internal FPGA RAM and ROM components
+             transceiver/  -- non bonded gigabit transceivers
+
+All files in the altera/ and xilinx/ IP directories start with prefix 'ip_' followed by the vendor library name and then a component name.
+All files in the technology independent IP directories start with prefix 'tech_' followed by the technology directory name and then a component name.
+
+The technology naming convention nicely clarifies the level of the component. The 'ip_' prefix indicates vendor specific IP and garantuees a name
+that will be different from any name that the vendor may use for its components. The 'tech_' prefix indicates the that the component is a wrapper
+component that acts as a portal between the technology independent application and the technology dependent IP.
+
+The default technology can be selected via the c_tech_select_default constant in technology_select_pkg.vhd or it can be passed on through the
+hierarchy via the g_technology generic.
+
+The vendor IP components are typically pregenerated by the MegaWizard in case of Altera and Coregen in case of Xilinx. For each variation of
+parameters it may be necessary to pregenerate an IP component. Alternatively for many Altera IP components it is allowed to add generics to
+the IP sources to make some parameters configurable without having to run the MegaWizard for each variation.
+
+Each technology independent component directory contains a tech_<dir_name>_component.pkg that lists the IP components from the vendor IP directories.
+The tech_<dir_name>_component.pkg makes all vendor IP known to the synthesis tool, while allowing the synthesis tool to ignore all foreign vendor IP. 
+Only the vendor IP libraries that are realy needed for the selected technology need to be made available for synthesis. Similar for simulation only
+the actually used vendor IP libraries need to be avaiable. However in simulation it is also allowed to make all vendor IP libraries available. The
+'tech_<directory_name><component name>.vhd' technology independent component files have a IP library clause that declares the IP libraries to ensure
+default binding in simulation. The IP library clause is ignored by synthesis. E.g. LIBRARY ip_altera_mf_lib, LIBRARY ip_stratixiv_hssi_lib.
+The default component to entity binding works because there is only one entity-architecture implementation for each component, because thanks
+to the IP naming convention with prefix 'ip_<vendor_library_name><component_name>.vhd' all IP components will have a unique name.