Skip to content

Core Inclusion Guide

Jump to bottom
mithro edited this page Sep 25, 2014 · 1 revision

The HDMI2USB project contains numerous third party "cores" used to enable functionality of the device. This guide has been written to give guidance on when selecting (or replacing) "cores".

  • "cores" is used loosely to just mean pretty much any code.

Selection Process

The selection process is a choice of balancing many issues. Where possible;

  • Choose open code.
  • Choose open standards.
  • Choose actively used cores and standards.
  • Choose wisely.

Popularity

Where possible choose cores which are popular even when they might be worse. Code with active communities tend to improve without needing effort, while things without them only improve proportional to the effort you put into them. The network effect also plays a strong part here.

For a great example of this, see what happened in git verse bzr.

Licensing

Where possible a core which has the full source code released under a FOSS License that has been used in production should be strongly preferred.

The order of FOSS license preferences are;

  1. Apache 2.0 - IE Do what you want with explicit patent grants.

  2. GPL 3.0 / LGPL 3.0 - IE "Share and Share Alike" with explicit patent grants.

  3. GPL 2.0 / LGPL 2.0 / CC-BY-SA - IE "Share and Share Alike" with implicit patent grants.

    • Not all CC licenses fall under the "fully open" requirement. ND and NC variants are explicitly not.

  4. BSD / MIT - IE Do what you want with implicit patent grants.

  5. Other OSI approved licenses.

    • Prefer explicit patent grants over implicit grants.
    • Be careful about licenses which explicitly exclude patents.

Non FOSS Licensed Core

Due to the realities of current FPGA development, code that is not released under a FOSS license made need to be used. All code in this state should be clearly marked for replacement with a fully open versions.

All cores must be licensed for unlimited free distribution for commercial use but may be tied to specific hardware.

here are two categories;

  1. Full source for core released with restrictions making it not-FOSS compatible. This includes;
  • Example code produced by from Xilinx / Altera that are only allowed to be used on certain FPGA devices.
  1. Partial source for core with associated binary "blob" which is freely modifiable and distributable. This includes;
  • Code output created by "core generators" such as found in Xilinx ISE and similar tools.
  • Code which requires an "vendor provided library" which needs to be included in the firmware.

Languages

The order of language preferences are;

  1. Verilog / VHDL
  2. MyHDL
  3. migen.hdl
  4. Other

There is a slight preference for Verilog over VHDL (despite VHDL being a lot cleaner) because of the availability of open source Verilog tools.

Testing

Cores which have been used in production like settings are strongly preferred to experimental or academic settings.

Cores which have strong test suites should be preferred to cores which have little or no test suites (which sadly is most of them :( ).

Cores which are popular, and thus have many users are also strongly preferred.

Importing Process

Much of the current HDMI2USB repository does not meet these following guidelines at the moment but will hopefully be in the future.

The following requirements are mandatory;

  • The licensing conditions for the core should be known. Don't copy stuff of a random website which doesn't include a license.
  • Third party code should be placed in the third_pary directory.
  • A README.md with the following information should be added to the imported directory;
FIXME: Add README template here.
  • The README should document clearly the restrictions on usage of the code.

HDMI2USB website

Clone this wiki locally