BETTERCP/M COMPATIBILITY POLICY =============================== Draft 0.1 1. PURPOSE 2. COMPATIBILITY PRINCIPLE 3. COMPATIBILITY CLASSES 4. EVIDENCE 5. EVIDENTIARY DISCIPLINE 6. COMPATIBILITY DECISIONS 7. DOCUMENTED VERSUS DE FACTO COMPATIBILITY 8. HARDWARE-DEPENDENT BEHAVIOR 9. COMPATIBILITY AND INTERNAL IMPLEMENTATION 10. CONFORMANCE 11. COMPATIBILITY LEDGER 12. POLICY PRINCIPLE 1. PURPOSE ---------- BetterCP/M is intended to provide a highly compatible CP/M 2.2 operating environment while remaining a new implementation. Compatibility is defined primarily in terms of behavior observable by CP/M programs, users, and software that legitimately interacts with the operating-system interfaces. BetterCP/M is not required to duplicate the internal organization, algorithms, source structure, or implementation techniques of Digital Research CP/M 2.2 except where those details produce externally observable behavior required for compatibility. This document defines how potential compatibility requirements are identified, classified, evaluated, and adopted. 2. COMPATIBILITY PRINCIPLE -------------------------- The central compatibility question is: What behavior must BetterCP/M reproduce so that software written for CP/M 2.2 encounters the operating environment on which it reasonably depends? The fact that Digital Research CP/M 2.2 exhibits a behavior does not, by itself, make that behavior a BetterCP/M compatibility requirement. Conversely, the absence of a behavior from published documentation does not, by itself, make that behavior irrelevant. Existing software may depend upon stable and widespread behavior that was never formally documented. Compatibility decisions shall therefore consider documentation, original implementation behavior, experimental observation, and evidence of actual software dependency. 3. COMPATIBILITY CLASSES ------------------------ Potential compatibility behavior shall initially be classified into one of the following categories. 3.1 DOCUMENTED CP/M 2.2 CONTRACT A documented behavior is one explicitly specified, or clearly required, by authoritative Digital Research documentation applicable to CP/M 2.2. Examples include the transient-program entry address at 0100h, the warm-boot gateway at 0000h, the BDOS gateway at 0005h, and the default DMA buffer at 0080h. Documented behavior is presumed to be a BetterCP/M compatibility requirement unless: * the behavior is optional in CP/M 2.2; * the behavior applies only to a particular hardware configuration or BIOS; * the documentation is ambiguous or contradictory; or * BetterCP/M explicitly documents an intentional incompatibility. Such exceptions shall be recorded rather than silently assumed. 3.2 OBSERVED DRI CP/M 2.2 IMPLEMENTATION BEHAVIOR Observed implementation behavior is behavior established from original Digital Research CP/M 2.2 source code, identifiable DRI binaries, or controlled experiments against an appropriate reference system, but which has not been established as part of the documented CP/M 2.2 contract. For example, the DRI CCP enters a transient program using CALL 0100h, thereby leaving a valid return address on the transient program's stack. Observed implementation behavior is evidence, not automatically a BetterCP/M requirement. It shall be investigated further when software could reasonably observe or depend upon it. 3.3 DE FACTO COMPATIBILITY BEHAVIOR De facto compatibility behavior is behavior not established as part of the documented CP/M 2.2 contract but for which there is sufficient evidence that existing CP/M software depends upon it. Evidence may include: * use by significant existing CP/M applications or utilities; * repeated use by independently developed software; * treatment as an expected convention in contemporary programming material; * reliance by widely used CP/M extensions or replacement components; * consistent behavior across relevant DRI CP/M 2.2 systems; or * other evidence demonstrating that changing the behavior would cause otherwise valid CP/M software to fail or behave incorrectly. A de facto behavior may be adopted as a BetterCP/M compatibility requirement even though Digital Research did not formally document it. The strength and scope of the evidence shall be recorded. 3.4 IMPLEMENTATION-SPECIFIC OR INCIDENTAL BEHAVIOR Implementation-specific behavior is observable behavior for which there is no evidence that software is entitled or known to depend upon it. Examples may include residual register values, stale bytes in unused buffer space, exact internal addresses, or values left behind by the particular sequence of instructions executed by the DRI CCP or BDOS. Such behavior shall not normally be reproduced by BetterCP/M. Incidental behavior shall not become a compatibility requirement merely because a probe can observe it. If later evidence demonstrates a genuine software dependency, the behavior may be reclassified. 3.5 UNKNOWN OR UNRESOLVED BEHAVIOR A behavior is unresolved when the available evidence is insufficient, ambiguous, contradictory, version-dependent, or otherwise inadequate for a compatibility decision. Unresolved behavior shall be recorded as such. BetterCP/M shall not silently convert uncertainty into either a requirement or a rejection. Additional documentation research, source inspection, experiments, or software testing shall be performed when the issue becomes relevant to implementation or compatibility. 4. EVIDENCE ----------- Compatibility findings may draw upon several kinds of evidence. No single source shall automatically answer every compatibility question. 4.1 DIGITAL RESEARCH DOCUMENTATION Digital Research documentation applicable to CP/M 2.2 is the primary source for the documented operating-system contract. Documents shall be identified by title, edition or version where available, and relevant section or page. Material describing CP/M 1.x, CP/M 3, MP/M, or other systems shall not be treated as CP/M 2.2 authority unless independent evidence establishes that the relevant behavior also applies to CP/M 2.2. 4.2 ORIGINAL DIGITAL RESEARCH IMPLEMENTATION Original DRI source code and identifiable DRI CP/M 2.2 binaries may be used to establish actual implementation behavior. Source-code behavior shall not automatically be treated as documented or required behavior. Where source versions differ, the difference shall be recorded when it could affect compatibility. 4.3 EXPERIMENTAL OBSERVATION Controlled experiments may be used to establish behavior of an identifiable CP/M 2.2 reference environment. The reference environment, emulator or hardware, system image, relevant configuration, test program, and limitations of the experiment shall be recorded sufficiently to make the result reproducible. An experiment establishes what the tested system did. It does not, by itself, establish that every CP/M 2.2 system must do the same thing. 4.4 EXISTING SOFTWARE Existing CP/M software is important evidence for de facto compatibility. Where undocumented behavior is suspected of being compatibility- significant, representative software should be examined or tested when practical. A hypothetical possibility that software could observe a behavior is not sufficient evidence that the behavior must be reproduced. 4.5 SECONDARY SOURCES Contemporary programming guides, technical articles, later documentation, emulator implementations, replacement operating-system components, and other secondary sources may identify behaviors worthy of investigation. They shall not silently replace applicable DRI documentation, original source, or direct experimental evidence. Their provenance and relevance shall be considered when assigning weight. 5. EVIDENTIARY DISCIPLINE ------------------------- Compatibility investigations shall distinguish among: * what the documentation says; * what the DRI implementation does; * what experiments demonstrate; * what existing software depends upon; * what is inferred; and * what remains unknown. Agreement among these sources strengthens a finding but shall not be manufactured where a source is silent. Where practical, important findings should record an evidentiary chain such as: claim -> documentation evidence -> source-code evidence -> experimental evidence -> software-dependency evidence Not every finding requires every form of evidence. Conflicts between evidence sources shall be recorded rather than silently reconciled. 6. COMPATIBILITY DECISIONS -------------------------- Classification describes the evidence. It does not by itself constitute a final BetterCP/M design decision. Each compatibility-significant behavior shall ultimately receive an explicit BetterCP/M disposition such as: REQUIRED BetterCP/M shall reproduce the behavior. OPTIONAL The behavior may be provided but is not required for baseline compatibility. NOT REQUIRED BetterCP/M need not reproduce the behavior. DEFERRED A decision is postponed pending additional evidence or implementation experience. UNRESOLVED No responsible decision can yet be made. The Compatibility Ledger shall record the classification, evidence, BetterCP/M disposition, rationale, and associated conformance tests. 7. DOCUMENTED VERSUS DE FACTO COMPATIBILITY ------------------------------------------- BetterCP/M shall not define compatibility so narrowly that only published API documentation matters. CP/M existed as a practical software platform. Stable conventions outside the formally documented interface may therefore be compatibility-significant when real software relies upon them. At the same time, BetterCP/M shall not attempt byte-for-byte emulation of every incidental consequence of the DRI implementation. The purpose of compatibility investigation is to distinguish these cases. For example, Investigation 001 established that DRI's CCP enters a transient program with CALL 0100h, leaving a valid return address on the stack. Whether immediate RET termination should be required depends upon evidence that this behavior formed part of the practical CP/M programming environment. By contrast, particular register values left by the DRI CCP at program entry are merely implementation residues unless evidence establishes a software dependency upon them. 8. HARDWARE-DEPENDENT BEHAVIOR ------------------------------ CP/M 2.2 deliberately separates hardware-dependent BIOS behavior from the portable operating-system environment. Behavior specific to a particular BIOS, disk controller, console, memory configuration, emulator, or physical machine shall not automatically become a general BetterCP/M compatibility requirement. Where software legitimately interacts with documented BIOS interfaces, BetterCP/M shall reproduce the required interface semantics while allowing the underlying implementation to differ. Hardware-specific behavior may be recorded separately when needed for a particular BetterCP/M platform. 9. COMPATIBILITY AND INTERNAL IMPLEMENTATION -------------------------------------------- BetterCP/M may use internal structures and algorithms substantially different from Digital Research CP/M 2.2. Compatibility requirements constrain externally observable behavior, not private implementation. BetterCP/M may therefore redesign internal: * data structures; * algorithms; * component organization; * memory-management techniques; * storage translation; * command-environment implementation; * hardware abstraction; and * other private mechanisms provided required CP/M-compatible behavior is preserved. An internal difference becomes a compatibility concern only when it changes behavior visible across a compatibility boundary. 10. CONFORMANCE --------------- Every compatibility requirement should be testable where practical. Accepted requirements shall therefore be associated with conformance tests capable of distinguishing compliant behavior from incompatible behavior. Tests may operate at several levels, including: * individual interface behavior; * page-zero and memory conventions; * BDOS services; * FCB and file-system behavior; * program loading and termination; * command-environment behavior; * BIOS-facing behavior; and * execution of representative existing CP/M software. Diagnostic tests may also record implementation-specific behavior without treating differences as failures. The Conformance Strategy defines the detailed test methodology. 11. COMPATIBILITY LEDGER ------------------------ The Compatibility Ledger is the authoritative record of investigated compatibility behaviors and BetterCP/M dispositions. Each ledger entry should identify, as applicable: * behavior under investigation; * compatibility classification; * documentary evidence; * DRI source or binary evidence; * experimental evidence; * software-dependency evidence; * unresolved questions; * BetterCP/M disposition; * rationale; and * associated conformance tests. The ledger is expected to evolve as research and implementation expose new compatibility questions. A previous decision may be reconsidered when materially stronger evidence becomes available. 12. POLICY PRINCIPLE -------------------- BetterCP/M seeks compatibility with the CP/M 2.2 software environment, not imitation of the accidents of one CP/M 2.2 implementation. Documented behavior provides the foundation. Actual DRI behavior provides essential evidence. Existing software determines whether undocumented behavior has become part of the practical compatibility contract. Implementation accidents remain implementation accidents unless evidence shows otherwise. Where the evidence is insufficient, BetterCP/M shall record the uncertainty and investigate rather than guess.