Embedded Open Modular Architecture/EOMA68/Software

= EOMA68 Software / OS Requirements =

This section covers the extensive and comprehensive perspective of the anticipated software-related lifecycle of EOMA68 Cards and Housings. It is broken down into roles. Whilst it is not necessary for all parties to fulfil all roles, it is generally a good idea for all parties to be aware of the responsibilities and obligations of other "roles".

= Manufacturers and OEMs =

This section is broken down into the roles and responsibilities that apply separately to Cards and to Housings. However there are different kinds of Cards, so these are distinguished and dealt with separately. The term "Manufacturers" is used in the context of covering a wide variety of people who may be collaborating together. For example, there may be a "Hardware Manufacturer" and the Card is then passed on to a "Software Manufacturer", but for the purposes of this section, the word "Manufacturer" is designated to not distinguish between these roles, and assumes a perspective that such distinctions are "in-house".

It is important to recognise the scope of a Manufacturer's responsibilities, in relation to other roles. Roles are bolded and capitalised for emphasis.


 * MANUFACTURERS may apply for Certification, but they may NOT pass on Cards or Housings over to RETAILERS until Certification is successful.
 * MANUFACTURERS are NOT directly responsible for honouring warranties with RETAIL_END-USERS unless they are also acting in the additional (separate) capacity as RETAILERS
 * MANUFACTURERS should consider their obligation to RETAIL_END-USERS (even though those obligations are actually carried out on their behalf via RETAILERS) is discharged (comes to an end) if the RETAIL_END-USER passes a Card or Housing on to a RECYCLER, a TECHNICAL_END-USER, a LIBRE_ENGINEER or destroys it, or if the RETAIL_END-USER chooses to invalidate the warranty (even though the warranty is actually covered by the RETAILER).
 * MANUFACTURERS have no direct obligation to TECHNICAL_END-USERs although there are several potential very indirect routes which should not be ignored or taken lightly.

Cards with on-board CPUs
Cards which contain an on-board CPU (and associated memory and storage) are where the OS and the Software is to be executed. Thus, for the role of "Manufacturer", it is the Manufacturer is primarily, immediately and directly responsible for ensuring that the Card is compliant with the EOMA68 Hardware and Software requirements. These responsibilities are permitted to be "outsourced", however it is is critical to note that Manufacturers may NOT self-certify compliance with the EOMA68 Specification, and are ONLY permitted to apply to Authorised EOMA68 Compliance Agents for validation, compliance and testing. This is primarily for safety reasons.


 * 1) A Card with a CPU MUST be capable of operating as a stand-alone computer. Therefore, logically, it MUST either have on-board or removable storage from which to boot, or it MAY have sufficient on-board resources (within the available power budget) to perform some type of "network" boot, whether that be Wired or Wireless.
 * 2) If a Manufacturer chooses some form of boot process that relies critically and exclusively on "download" of any software involved in the boot process and/or the operation of the device, whether that be over Ethernet, HDMI-Ethernet, USB-based booting or Wireless forms (including 802.11, 802.22 or other forms such as GPRS / EDGE / 3G / 4G / LTE / 5G), great care must be taken to ensure that the means and method is anticipated to be available at a reasonable cost that not only the initial end-user is happy with, but that the ongoing end-users further down the lifecycle chain of the Card may also reasonably expect to have access to.  If there is any reason that is suspected why such expectations are unlikely to be met (even such as "the 3G network is DRM-locked to a particular provider"), Certification will NOT be granted.  It is however acceptable to have a means and method to boot in the absence of such "network" boot methods, such that the Card's full operation and function is entirely unaffected by the absence of such "network" booting methods.
 * 3) A Card MAY utilise separate internal storage media for "BIOS" or other early self-initialisation: exact means and methods of self-bootstrapping / self-initialisation are beyond the scope of this document and are entirely at the discretion of the Card Manufacturer.  Note: DRM-locking of the early self-initialisation code is NOT permitted (see DRM section).
 * 4) However, at some point in the boot chain, selection of an OS (including a default OS) MUST begin: this MUST be from either on-board or removable storage (or from internal RAM disks that happened to be initialised as part of an earlier network-boot phase).  Reminder: DRM-locking is NOT permitted during any of these phases (see DRM section).
 * 5) During all and any boot phases (first early BIOS boot, post-initialisation boot) and all and any subsequent operation (including the running of OSes), the software MUST be configured so as to read the EOMA68 I2C EEPROM (format TBD) in order to ascertain the existence and presence of any "Housings" and, in the case of the early BIOS boot, the existence and presence of any external Housing boot media.
 * 6) Ordinarily, the power-on boot phase (part of the actual CPU's on-board boot-up process) is outside of the control of the Manufacturer of the Card as it is pre-specified by the CPU designer.  This process could potentially be disruptive to Housings if the CPU were to be connected to a Housing that, for example, utilised certain pins for GPIO but the CPU was expecting them to be an SD/MMC "boot media" for example.  It is therefore the responsibility of the MANUFACTURER to ensure that the CPU is kept under control during this power-on phase.  An example is the ICubeCorp IC1t which has three hardware pins dedicated to boot selection.  By analysing the IC1t datasheet, then pre-selecting the correct hardware pins and selecting only the appropriate pins to be routed through to the EOMA68 Interface, potential disruption is completely avoided of all and any Housings under all and any circumstances for normal END-USER deployment.
 * 7) If it is not a practical option for the selected CPU (alone) to be placed into a mode where its power-on boot process could result in disruption of any peripherals accessible through the EOMA68 interface, the Manufacturer MUST add suitable buffering ICs that will provide tri-state protection so as to isolate the potentially-disruptive pins, whilst also ensuring that those tri-state buffers may be returned to a mode that does not affect compliance with the rest of the EOMA68 Specification (in particular the pinouts and interfaces section).  This MAY be implemented simply as a delay (using hardware), as long as the subsequent boot process can take this into account.
 * 8) It is NOT the responsibility of the Manufacturer to cater for "abnormal" circumstances, for example if the end-user discovers (and activates) a "Factory Boot Mode".
 * 9) With the exception of "genuine safety reasons", Manufacturers are NOT permitted to prevent any third party from discovering or operating the Card outside of its "normal" pre-configured mode (as deployed and sold either through them in their capacity and role as a "Retailer", or by any independent Retailer).  The best way to comply with this requirement is to have an internal "jumper" or "switch" actually inside the Card which is completely inaccessible under normal circumstances, such that the Warranty (if there is one) can provably be said to have been invalidated before the Card is capable of being placed into such "modes".
 * 10) Manufacturers are NOT permitted to prevent any third party from taking any action that would invalidate the warranty.
 * 11) With the proviso that the third party accepts that they have by this point already invalidated the warranty: assuming that the Card has not been damaged by lack of care by a third party in opening it up, the Card MUST continue to be operational without reduced capacity or function, whether it is operated in its disassembled state or whether it is reassembled.
 * 12) The erasure of all and any internal media and all and any data (including but not limited to boot media) is permitted as a means or method of "tamper-resistance", but the Card MUST be "recoverable" to a known-good state (without requiring specialist software, equipment or tools).  If such specialist software is required, it must be freely available and compliant with Software Libre Licenses.  If specialist tools or equipment is required, it should be of a type that is commonly and readily available, or the means and method of its manufacture and assembly should also be unrestricted and commonly available.  For an extremely relevant example of what is NOT permitted, see the dog's dinner mess surrounding vehicle "On-board Diagnostics" tools and equipment.
 * 13) The blowing of internal e-fuses or writing to NAND, PROMs or EEPROMs in on-board CPUs or other ICs which, as a direct consequence of those actions being taken results in the Card being reduced in capacity or function (including boot, access to media and peripherals, or otherwise restricting the Card's usefulness and/or ability to be subsequently compliant with all aspects of the EOMA68 Specification), and which would require specialist equipment to replace, is NOT permitted.
 * 14) The blowing of internal e-fuses or writing to NAND, PROMs or EEPROMs in on-board CPUs or other ICs which, as a direct consequence of those actions being taken GUARANTEES that the Card remains compliant with all aspects and requirements of the EOMA68 specification, is permitted, as long as there is a means to temporarily revert or bypass the restriction (such as a "jumper setting" or switch or other suitable method) i.e. without specialist equipment being required to replace the affected ICs. This is a particularly useful action to carry out after factory-deployment: an on-board SPI boot ROM could be set into "read-only" mode after first factory initialisation.  If however the e-fuse may not be replaced without specialist equipment, it is important that it only be used for software-only detection purposes, where the software may be easily replaced by the end-user with a version that simply ignores the state of the e-fuse... WITHOUT the end-user being penalised for doing so (such as claiming that the warranty is now invalid).
 * 15) If the Card is inserted into a Housing, it MAY at any time during the boot sequence or subsequent operation look for early-boot (BIOS) media, boot media and/or boot loaders and/or OSes and/or Software through the detection, initialisation of any "media" (including network-attached media) that is discovered.  However, the Card MAY NOT simply assume the existence or presence of such "media", and must have some form of "fallback" position such that it may continue to function (in effect as a stand-alone computer).  In addition, Manufacturers need to be keenly aware that even their own future Cards may use processors that are completely incompatible with the software that was found on such media, especially if the media is non-removable.  The only circumstances therefore under which it might be acceptable is if there are additional applications which are entirely written in processor-agnostic programming languages, or perhaps are a "Virtual OS".  Great care should be taken to ensure that the required resources to run the software are not beyond the capability and resources of third party Cards, so as a general rule the entire practice of deploying software on non-removable media is discouraged.
 * 16) The Card MAY be supplied (sold direct or through chains ultimately on through to retailers) by the Manufacturer with a SINGLE EOMA68-compliant OS, where "adaptable support" for the Manufacturer's own Housings (past and present) is REQUIRED.
 * 17) If the Manufacturer utilises Libre-compliant Source for all aspects of the operation of the Card (right from boot through to normal operation) and is in FULL LEGAL COPYRIGHT COMPLIANCE with ALL SOFTWARE LICENSES, and provides FULL DOCUMENTATION without requiring NDAs for access to full information regarding the Hardware on the Card at the time of release of the Card, then Manufacturers are NOT required to provide "adaptable support" for Housings that are not manufactured specifically by them.  The best way to ensure compliance with this requirement is to apply for (and successfully receive, and continue to have valid) FSF "RYF" (Respect Your Freedom) Certification.
 * 18) If during the lifetime of the Card an additional Housing is released by the Manufacturer, the Manufacturer SHOULD provide a "Software Upgrade" for the Card's OS, such that the Card now provides "adaptable support" for the newer Housing being included as part of the "present set of Housings".
 * 19) A Manufacturer is RECOMMENDED to consider developing and then supplying multiple OSes for one particular Card, especially given that Housings supplied by the Manufacturer itself may be for a completely different purpose, during the lifetime of the Card.
 * 20) The Manufacturer MAY allow the OS or bootloader to have a "multi-boot" option in order to support its own range of Housings.  It MAY also utilise "Virtual Machine" support of the on-board CPU as a means or method to provide that "multi-boot" support.  In effect: all and any available options are permitted and encouraged so as to meet the end-user's requirements and to ensure the EOMA68 tagline "Just Plug It In: It Will Work" is met, for all products that the Manufacturer designs.
 * 21) IMPORTANT EXCEPTION.  If the Manufacturer utilises ANY proprietary software, the burden of support and responsibility for ALL EOMA68-compliant Housings (past, present and future including third party Housings) shifts automatically and exclusively to the MANUFACTURER.  Thus, if a single piece of software is proprietary and comes pre-installed on the Card, it is REQUIRED that the Manufacturer take sole, complete and total responsibility for ensuring that the proprietary software be validated as fully-functional, in perpetuity across the entire past, present and future range of EOMA68 Housings, whether those Housings be from the Manufacturer themselves or whether they be from 3rd parties.  This responsibility MAY be outsourced to Authorised EOMA68 Certifications-compliance Agents, however the Manufacturer needs to take into account that it is perfectly reasonable for such authorised agents to charge for the Certification and Testing Process of all and any proprietary software presented.  Manufacturers should also be aware that the process is not a "one-off, fire-and-forget" process: continuous on-going re-certification is REQUIRED.  About the only possible exemption here is if the proprietary software is run in a "virtualised container" in a similar (isolated) method as described in the "DRM" section (note: not that the virtualisation software itself is proprietary).  However this may require evaluation, depending on the circumstances and method deployed, so if in doubt it is best to contact the author of the EOMA68 Specification.

Cards designed with Security features
Cards with security features have completely different requirements that are in direct conflict with the otherwise open mindset behind EOMA68. As such, there will be special exemptions made (yet to be determined). However, a critical design rule shall apply: "security through obscurity", "snake oil" and other false and misleading designs will not be tolerated. Cards with security features that are implemented incompetently with blatant disregard for actual "secure design" (in both the hardware and software) could bring EOMA68's reputation into disrepute, and thus will not be tolerated.

In general, except where it is demonstrated to be completely necessary (Classified environments for example), the source code is expected to be available for public review.

Housings
Housings range from simple break-out boards, through "peripheral-extender" style devices (similar to the old laptop "docking stations") to fully-functioning autonomous devices where the insertion of an EOMA68 Card is merely an "augmentation". With this much versatility, the burden primarily falls onto Cards. However there are still some key guidelines and requirements:


 * 1) Manufacturers are NOT permitted to self-certify Housings as being compliant with the EOMA68 Specification, and may not utilise the phrases "EOMA68 Compatible" or "EOMA68 Compliant" or any equivalents without permission from an Authorised EOMA68 Compliance and Certification Agent.  The reasons are extremely simple: safety is paramount.  This is hardware.  Design mistakes (and design flaws) can be made.
 * 2) Manufacturers MUST apply for a unique 4-byte "Manufacturer Identification Code" (MIC) from an Authorised EOMA68 Compliance and Certification Agent only, and MUST accept that this information is both public and immediately published as a supplemental resource associated with the EOMA68 Specification (publication location TBD).
 * 3) Manufacturers MAY create Housing-specific unique 4-byte identifiers, and MUST publish these, in exactly the same fashion as is utilised for USB and PCI.
 * 4) Manufacturers MUST ensure that when the Housing leaves their factory, the EOMA68 I2C EEPROM contains the unique 4-byte MIC (location and format TBD)
 * 5) The Housing-specific unique 4-byte identifier MUST also likewise be stored in the I2C EEPROM (location and format TBD).
 * 6) When designing Housings, Manufacturers MUST be aware of their obligations wrt DRM and Tivoisation (i.e. it is simply not permitted)
 * 7) Manufacturers that design Housings containing "storage" or permitting external or internal removable storage to be plugged in (whether the socket be inside the Housing or outside the Housing) should bear in mind that, whilst it is permitted for such external media to be utilised for boot purposes, they have no obligation or requirement under the EOMA68 Specification that such storage media be present at any time (including boot time) or even provided at all, safe in the knowledge that Cards are in no way permitted to expect such media to be present for any purpose.  Even a Housing which does not even have any boot or storage media, nor provides a means or method of accessing such media, is perfectly acceptable, and in the case of certain types of Security-related Housings, may actually even be desirable.
 * 8) Manufacturers that design Housings which contain internal non-removable storage intended for the purpose of "booting" or "applications" need to bear in mind that Cards have different CPUs or may not even have a CPU at all.  Any such booting or application software is therefore extremely unlikely to work except on a highly limited range of Cards.  This practice is therefore STRONGLY discouraged, in favour of utilising either removable media, Virtual Machines, or processor-agnostic applications (python, perl, java bytecode).  However even here there is still no guarantee that the application will function correctly (missing dependencies, out-of-date dependencies) or in the case of Virtual Machines, the Card simply may not be capable of executing the software due to a lack of resources.  Thus, once again, the practice is STRONGLY discouraged.
 * 9) Manufacturers are under no obligation to provide external access (except through the EOMA68 hardware interface) to any internal components or storage media (bootable or otherwise), and (apart from through the EOMA68 hardware connector itself) are perfectly at liberty to create Secure Housings or tamper-resistant Housings.  However, there should be no expectation or requirement that any Card (supplied by the Manufacturer or by a party considered to be a 3rd party from the perspective of the Manufacturer) SHALL boot FROM internal or external media within or attached to the Housing (secure or otherwise).
 * 10) If there is any "secure media" or other peripheral provided as part of the Housing (including detached peripherals that may reasonably said to be "part of the Housing" i.e. the Housing is functionally useless or greatly reduced in function without that peripheral, internal or external), the means by which the media or peripheral is accessed (passphrase, password, dongle, 2-factor authentication procedure) SHALL be made public, published IN FULL without NDAs, royalties or any other restrictions, either on use, implementation, distribution of implementations in source or binary form, nor shall there be any restriction or limit placed on the scope of discussion of implementations, such that any party may have the reasonable expectation of being able to access the "secure media" through the installation of a 3rd party software implementation, even if the Manufacturer no longer provides a warranty for the Housing or the peripheral, or no longer sells the Housing (or peripheral), or is simply no longer is in business.  The Manufacturer shall also warrant that these conditions (in spirit as well as in reality) shall apply even if the Manufacturer sells the Housing design (or peripheral, if designed by the Manufacturer) onto a third party, or if the Manufacturer is bought by another company.
 * 11) When designing and selling a Housing, the use or reliance on 3rd party peripherals by the Manufacturer which require NDAs, binary firmware, or other restricted devices, components, peripherals or media, which could reasonably said to be in direct conflict with the tagline "Just Plug It In: It Will Work", are NOT PERMITTED.  Whilst this restriction may seem extreme, a "workaround" is to make the peripheral or component end-user removable, to ensure that it is not a primary part of the Housing's marketed purpose, and to ensure that there exist third party alternative peripherals or components that perform a similar function.  The most common example is WIFI peripherals, the majority of which require proprietary firmware.  Even if there exists one such peripheral (such as the Atheros AR9271-based TP150N which is fully-supported by the ath9k_htc linux kernel module and has libre firmware available for it), the obligations of the Manufacturer may reasonably said to have been met.  Again, the simplest way to check if the Housing is compliant is to apply for (and be successfully granted, and to maintain and not have revoked) the FSF's "RYF" (Respects Your Freedom) Certification.
 * 12) Whilst it is preferred that the Manufacturer provide a means or method by which software on associated Cards is made available (i.e. aid and assist as part of the pre-installed software a means for "upgrades" or "software" to be installed in a reasonably-easy and non-disruptive fashion), a Manufacturer MAY designate the END-USER as being wholly responsible for the installation of third party proprietary software or firmware (libre or otherwise) for any third party peripherals or components (internal or external) that the END-USER chooses to connect to the Housing (or install in the Housing, if it has internal space).
 * 13) The Manufacturer MAY NOT prevent or prohibit ANY party from doing same, in any way.  Common sense shall prevail as to whether this has any effect on the Manufacturer's warranty obligations (if the Manufacturer is also acting in any capacity under the role of a Retailer).

= Libre Software, PCB and Casework Engineers =

This project happens to be one of the extremely rare Libre Projects where the consequences of making mistakes at an earlier phase could have disastrous unforseen consequences, even when Libre-licensed Software, PCB and Casework is a critical part of the picture. Most Libre Projects simply do not have that kind of scope or timeframe.

Libre Software, Libre PCB and Libre Casework Engineers are viewed as acting in the capacity / role role of "Manufacturers", and must still expect to be compliant with the EOMA68 Specification. However, if their work is public and published during the design phase, such that others may collaborate and/or copy and/or fork it even before it is released, Compliance Certification need not actually be sought (nor may even be sought). Thus there is a "workaround" (similar to the exemption that exists in patent law where anyone may "make" an instance of a patented invention for the purposes of improving it) where anyone may, as long as they accept sole responsibility and full liability, gain access to the full design files and manufacture them for their own personal purposes and use (however loosely that may be interpreted).

However, two "Gotchas" exist.


 * 1) During the development phase, no party may claim "EOMA68 Compliance" (or similar phrases) or use such phrases in any communications (private or public) which may give the impression that the product (or part) under development is "EOMA68 Compliant".  That includes parties who take copies of the design(s).  The only circumstances under which the product (Card or Housing) is submitted for testing to an Authorised EOMA68-Compliance Agent is when there are Production units ready to be submitted, prior to them being sold.  Thus, by definition, the paradox exists where pre-production units could have a wide distribution and usage (even in production environments) by a highly significant numerical quantity of people, yet every single one of them is, in the strictest sense, not compliant with the EOMA68 Specification, nor should they or could they even apply!
 * 2) The point at which such individuals or organisations become "Retailers" (for example by virtue of putting the manufactured parts or full products up for sale, whether privately or publicly), this is where the possibility exists that the people to whom the parts or products may be under the illusion (implied or expressed impression) that the parts or products are "EOMA68 Compliant" or have been Certified as such. At this point, then, it becomes necessary for such people considering becoming "Retailers" to obtain EOMA68 Compliance prior to the products transferring to of third parties, EVEN IF those parties are involved in the business of "waste disposal" (see recent failure of USA-based "waste disposal" experts to actually comply with their contractual and legal obligations).  To avoid the scenario where the non-compliant products (or parts) end up being quotes recycled quotes and actually end up being part of products that claim EOMA68 compliance without full and comprehensive testing being carried out, before leaving the hands of those who created them, the products (or parts) MUST be indelibly marked (defaced), destroyed, or otherwise made clearly and obviously non-functional.  Use of a pair of pliers or cutters to crack the PCB and remove a large chunk of it would be one method; bending pins off of connectors so that they are actually snapped off would be another, as would putting resin into various holes, or (if sufficient care is taken during the process) applying 100,000 volts for a duration of several seconds is a "fun favourite".

In essence, then, common sense should prevail. The idea of EOMA68 is to encourage people to develop Libre PCB and Libre casework for use in EOMA68 Cards and Housings, to collaborate in doing so, and ultimately to have the opportunity to financially benefit from doing so. However, given that that should not be done with a blatant disregard for the safety of others, it is required that people wishing to participate respect and accept the process and the constraints under which they must operate.

This scenario is not without precedent: it is extraordinarily similar to the situation in which the members of the "Auto-gyrocopter" Community find themselves, where ordinary people wishing to assemble and fly their own Auto-Gyrocopter may register as "Subsidiaries" of the "Parent Company" that designed the parts, in order to claim compliance with Safety Regulations that apply to the Aviation Industry (including to the assembly of pre-existing designs). However for those not familiar with this (or any other) example, it may come as a bit of a shock to Libre Software, PCB and Casework Engineers who, from working with or simply observing the day-to-day operation of other Libre Projects, would not normally expect to have such constraints imposed on them, especially those who may be familiar with such initiatives as OSHWA, OHANDA and others based around the concept of "Freedom". Such initiatives however are completely unlike the EOMA68 initiative in their goals and reach, so there is literally no valid comparison that can be made, either in the Libre world or even in the proprietary world.

To give an example which illustrates a critical difference between EOMA68 and OSHWA: OSHWA self-certification is permitted without restraint, due process, registration, declaration, liability insurance, and, amazingly, without requiring end-users to agree to, be aware of, be made aware of, or sign any documentation, waiver, warranty or even the actual OSHWA standard itself! The number of ways in which OSHWA self-certification violates common sense and exposes all parties involved to liability is both extreme and alarming. Yet it can be CLAIMED that OSHWA self-certification is neither onerous nor burdensome, and it is even approved of as being an "Open Specification"!

By contrast, with EOMA68, we have the strange and paradoxical apparent mismatch between EOMA68 being an open specification (with no patents having been taken out), yet at the same time that specification contains seemingly-arbitrary-like constraints, such that it even appears to no longer be a truly "open" specification, even though ultimately it reduces the risk of end-users coming to harm.

The author of the EOMA68 Specification (being a Libre Project Manager, Software Libre Engineer, Libre PCB Engineer, Libre Casework Engineer and advocate of all of the same) is keenly aware of how different working with EOMA68 is. Given that this is hardware (not software) and that it has people's safety as an over-arching priority which has to take absolute precedence, it is assumed that people will understand and accept that there genuinely are differences, and accept the constraints accordingly.

Ultimately then we must recognise and accept the responsibility associated with cooperating and collaborating on such a vast project with such a huge scope. "Freedom" - even the Four Freedoms associated with Libre Projects - does not mean "Freedom to ignore ethics or safety", nor does it mean "Freedom without wisdom" or "Freedom without thinking first of the consequences and curtailing action accordingly". In essence, we paradoxically need to STOP thinking of "Freedom as being a right", because there is a significant difference between having knowledge (of a techique) and taking action based on that knowledge. English Language is failing us, here: we need to recognise that, adapt accordingly, and act with WISDOM.

= Retailers =

TBD

= Recyclers =

TBD

= Technical End-users =

TBD

= Retail End-users =

TBD

= Conclusion =

TBD