@andrivet/z80-assembler 1.3.2 → 1.4.0

package/libs/z80-assembler/src/lib/compiler/Compiler.ts

@@ -0,0 +1,185 @@
+/**
+ * Z80 Assembler in Typescript
+ *
+ * File:        Compiler.ts
+ * Description: Compiler (assembler)
+ * Author:			Sebastien Andrivet
+ * License:			GPLv3
+ * Copyrights: 	Copyright (C) 2023 Sebastien Andrivet
+ */
+
+import {Parser, PosInfo} from "../grammar/z80";
+import {CompilationInfo, LinesInfo} from "../types/Types";
+import {CompilationError} from "../types/Error";
+import {computeLabels, generate} from "./Generator";
+import {resetLabels} from "./Labels";
+import {
+  assetBasicEnd,
+  assetBasicLine1,
+  assetBasicLine2,
+  assetCharacters,
+  assetDisplay,
+  assetSystemVariables
+} from "./Assets";
+
+/**
+ * Type of the internal data.
+ */
+interface ParseData {
+  // The name of the output file as declared by the output directive.
+  outputName: string,
+  // The name of the SLD file as declared by the output directive.
+  sldName: string,
+  // The name of the device as declared by the device directive.
+  deviceName: string,
+  // The base path of first file compiled. It is used to load included files.
+  basePath: string,
+  // The name of the current file compiled. It changes when a file is included and parsed.
+  fileName: string,
+  // The function to use when including a file to get its source code.
+  getFileCode: (filename: string) => string //
+}
+
+/**
+ * Internal data (i.e. globals).
+ * Unfortunately, tsPEG does not allow to declare a context for the parsing.
+ * So instead, we use this ugly global.
+ */
+const parseData: ParseData = {
+  outputName: "",
+  sldName: "",
+  deviceName: "",
+  basePath: '',
+  fileName: '',
+  getFileCode: () => ''
+};
+
+/**
+ * Set the outputs names (output directive).
+ * @param filename Filename for the binary.
+ * @param sld Filename for the SLD.
+ */
+function setOutputName(filename: string, sld?: string) {
+  parseData.outputName = filename;
+  parseData.sldName = sld ? sld : filename.replace(/\.P$/, '.sld');
+}
+
+/**
+ * Set the name of the target (device directive)
+ * @param name The name of the device
+ */
+function setDevice(name: string) {
+  parseData.deviceName = name.toLowerCase();
+}
+
+/**
+ * Include an assembly file (include directive).
+ * @param pos Position of the include directive.
+ * @param filename The filename of the file to be included.
+ */
+function includeFile(pos: PosInfo, filename: string): LinesInfo {
+  const filepath = parseData.basePath + filename;
+  // Ask the code for the file to be included
+  const code = parseData.getFileCode(filepath);
+  // Return the lines (AST) and the associated filename.
+  return parseCode(filepath, code);
+}
+
+/**
+ * Parse some assembly code.
+ * @param filename Name of the file corresponding to the code.
+ * @param code The code to parse.
+ */
+function parseCode(filename: string, code: string): LinesInfo {
+  // It is not possible to attach a context to the parsing, so use this dirty trick.
+  const oldFileName = parseData.fileName;
+  parseData.fileName = filename;
+
+  // If the code does not end with a new line, add it.
+  if(!code.endsWith('\n')) code += '\n';
+  // Declare a parser for the code.
+  const parser = new Parser(code);
+  // Parse the code.
+  const result = parser.parse();
+  parseData.fileName = oldFileName;
+
+  // If there is an error, raise an exception.
+  if(result.errs.length > 0)
+    throw CompilationError.fromSyntaxErr(filename, result.errs[0])
+  // Returns the lines, i.e. the AST
+  return {lines: result.ast?.lines ?? [], filename: filename};
+}
+
+/**
+ * Get the file name of a file path.
+ * @param filepath The file path.
+ */
+function getBasePath(filepath: string): string {
+  let index = filepath.lastIndexOf('/');
+  if(index === -1)
+    index = filepath.lastIndexOf('\\');
+  if(index === -1)
+    return '';
+  return filepath.substring(0, index + 1);
+}
+
+/**
+ * Compile an assembly source code.
+ * @param filepath The file path of the source code.
+ * @param code The assembly source code.
+ * @param getFileCode A function to get the content of included files.
+ */
+function compile(filepath: string, code: string, getFileCode: (filename: string) => string): CompilationInfo {
+  // Set default values globally
+  parseData.outputName = filepath.replace(/\..*$/, '') + '.P';
+  parseData.sldName = parseData.outputName.replace(/\.P$/, '.sld');
+  parseData.basePath = getBasePath(filepath);
+  parseData.getFileCode = getFileCode;
+
+  try {
+    // Reset the labels.
+    resetLabels();
+    // Parse this source code.
+    const parsed = postProcessing(parseCode(filepath, code));
+    // Compute the value of the labels.
+    computeLabels(0, parsed);
+    const generated = generate(filepath, 0, parsed);
+
+    // Generate the bytes, the SLD and return them.
+    return {
+      outputName: parseData.outputName,
+      bytes: generated.bytes,
+      sld: generated.sld,
+      errs: []
+    };
+  }
+  catch(ex: any) { // eslint-disable-line
+    // Return the errors.
+    return {
+      outputName: parseData.outputName,
+      bytes: [],
+      sld: '',
+      errs: [CompilationError.fromAny(parseData.fileName, ex)]
+    };
+  }
+}
+
+/**
+ * Processing of the AST after the parsing. This is used to inject code specific to the ZX81.
+ * @param info The parsed AST (lines).
+ */
+function postProcessing(info: LinesInfo): LinesInfo[] {
+  if(parseData.deviceName !== 'zx81') return [info];
+
+  return [
+    parseCode('@internal/characters.zx81', assetCharacters),
+    parseCode('@internal/system-variables.zx81', assetSystemVariables),
+    parseCode('@internal/basic-line1.zx81', assetBasicLine1),
+    info,
+    parseCode('@internal/basic-line2.zx81', assetBasicLine2),
+    parseCode('@internal/display.zx81', assetDisplay),
+    parseCode('@internal/basic-end.zx81', assetBasicEnd)
+  ];
+}
+
+export {parseData, compile, includeFile, setOutputName, setDevice};

package/libs/z80-assembler/src/lib/compiler/Formatter.ts

@@ -0,0 +1,43 @@
+/**
+ * Z80 Assembler in Typescript
+ *
+ * File:        Formatter.ts
+ * Description: Format bytes to display them easily
+ * Author:			Sebastien Andrivet
+ * License:			GPLv3
+ * Copyrights: 	Copyright (C) 2023 Sebastien Andrivet
+ */
+
+/**
+ * Represents a chunk of data to display binary.
+ */
+interface Chunk {
+  // The address of the chunk of data.
+  address: string;
+  // The bytes (converted to strings).
+  bytes: string;
+}
+
+/**
+ * Format bytes to display them.
+ * @param bytes An array of bytes.
+ * @param perLine Number of bytes per line.
+ */
+function formatBytes(bytes: number[], perLine: number): Chunk[] {
+  let data: Chunk[] = [];
+  let address = 0;
+  // For each byte...
+  while(address < bytes.length) {
+    // Cut a slice
+    const chunk = bytes.slice(address, address + perLine);
+    // Format the address and each byte
+    data = data.concat({
+      address: address.toString(16).padStart(4, '0'),
+      bytes: chunk.map(b => b.toString(16).padStart(2, '0')).join(' ')
+    });
+    address += perLine;
+  }
+  return data;
+}
+
+export {formatBytes, Chunk};

package/libs/z80-assembler/src/lib/compiler/Generator.ts

@@ -0,0 +1,255 @@
+/**
+ * Z80 Assembler in Typescript
+ *
+ * File:        Generator.ts
+ * Description: Generate bytes and SLD
+ * Author:			Sebastien Andrivet
+ * License:			GPLv3
+ * Copyrights: 	Copyright (C) 2023 Sebastien Andrivet
+ */
+
+import {ASTKinds, Line, Lines, Statement} from "../grammar/z80";
+import {bytes, LinesInfo} from '../types/Types';
+import {addLabel, addLabelExpression, getLabelValue, isLabelUsed, resetLabelsRecursion} from "./Labels";
+import {AstElement, AstElements, getByteSize, isAbstract} from "./Ast";
+import {parseData} from "./Compiler";
+
+
+/**
+ * Information about a compiled program.
+ */
+interface ProgramInfo {
+  // Bytes of the compiled program.
+  bytes: bytes;
+  // Name of the binary file.
+  outputName: string;
+  // Name if the SLD file.
+  outputSldName: string;
+  // Next address after the compiled bytes.
+  address: number;
+}
+
+/**
+ * Compute, whenever possible, the value associated with labels.
+ * @param address The starting address.
+ * @param infos The lines (i.e. the AST)
+ * @return the address that corresponds to the code after the lines (i.e. the new starting address).
+ */
+function computeLabels(address: number, infos: LinesInfo[]): number {
+  return infos.reduce((r: number, c: LinesInfo) => {
+    if(c.lines.length <= 0) return r;
+    computeEqualities(c.lines);
+    return computeVariableLabels(r, c.lines)
+  }, address);
+}
+
+/**
+ * Compute the value of labels associated with equalities.
+ * @param lines The lines (i.e. the AST)
+ */
+function computeEqualities(lines: Lines) {
+  // For each line...
+  for (const line of lines) {
+    resetLabelsRecursion();
+    // If it is an equality, add the label and its value (an expression).
+    if(line.kind === ASTKinds.LineEqual)
+      addLabelExpression(line.label.pos, line.label.name, line.equal.e);
+    // If it is a statement, and it contains an inclusion, compute recursively the labels for those lines.
+    else if(line.kind === ASTKinds.LineStatement && line.statement?.kind === ASTKinds.Statement_1)
+      computeEqualities(line.statement.inc.info.lines);
+  }
+}
+
+/**
+ * Compute labels with a value dependent of the code generated
+ * @param address The starting address.
+ * @param lines The lines (i.e. the AST)
+ * @return the address that corresponds to the code after the lines (i.e. the new starting address).
+ */
+function computeVariableLabels(address: number, lines: Lines): number {
+  // For each line...
+  for (const line of lines) {
+    // If it is not a line statement, the address remains the same.
+    if(line.kind !== ASTKinds.LineStatement) continue;
+    // If the line starts with a label, record it (and its address).
+    if(line.label) addLabel({filename: parseData.fileName, pos: line.label.pos}, line.label.name, address);
+    // If it is a statement, compute the new address (after the statement).
+    if(line.statement) address = computeAddress(address, line.statement);
+  }
+  return address;
+}
+
+/**
+ * Compute the address following a statement.
+ * @param address The starting address.
+ * @param statement The statement.
+ * @return the address that corresponds to the code after the statement (i.e. the new starting address).
+ */
+function computeAddress(address: number, statement: Statement): number {
+  switch(statement.kind) {
+    case ASTKinds.Statement_1:
+      // If it is an include statement, compute recursively the labels for those lines.
+      return computeLabels(address, [statement.info]);
+
+    case ASTKinds.Statement_2:
+      // If it is an instruction, increment the address by the number of bytes that will be generated.
+      return address + statement.elements.reduce((r: number, c) => r + getByteSize(c), 0);
+
+    case ASTKinds.Statement_3:
+      // If it is a directive, take either the address set by the directive (origin) or
+      // increment the address by the number of bytes that will be generated.
+      return statement.address ?  statement.address :
+        address + statement.elements.reduce((r: number, c) => r + getByteSize(c), 0);
+  }
+}
+
+interface GenerationData {
+  bytes: bytes;
+  sld: string;
+  address: number;
+}
+
+/**
+ * Generate machine code bytes and SLD for an array of lines (i.e. an AST)
+ * @param mainfile Main file name
+ * @param address The current address.
+ * @param infos The lines (i.e. the AST) with the associated filename
+ * @return An array of bytes (numbers), debug data and the next address
+ */
+function generate(mainfile: string, address: number, infos: LinesInfo[]): GenerationData {
+  // Generate the SLD header.
+  const header = '|SLD.data.version|1\n' +
+    `${mainfile}|1||0|-1|-1|Z|pages.size:65536,pages.count:32,slots.count:1,slots.adr:0\n`;
+  const generated = generateLines(address, infos);
+  return {bytes: generated.bytes, sld: header + generated.sld, address: address};
+}
+
+/**
+ * Generate machine code bytes and SLD for an array of lines (i.e. an AST)
+ * @param address The current address.
+ * @param infos The lines (i.e. the AST) with the associated filename
+ * @return An array of bytes (numbers), debug data and the next address
+ */
+function generateLines(address: number, infos: LinesInfo[]): GenerationData {
+  // Start with an empty array of bytes.
+  let bytes: bytes = [];
+  let sld = '';
+  let end = false;
+
+  // For each file...
+  for(const info of infos) {
+    // Each file starts at line 1.
+    let lineNumber = 1;
+    // For each line...
+    for (const line of info.lines) {
+      // If it is not a statement, take the next line.
+      if (line.kind !== ASTKinds.LineStatement || !line.statement) {
+        sld += generateSld(info.filename, lineNumber, address, line);
+        lineNumber += 1; // Next line
+        continue;
+      }
+
+      switch (line.statement?.kind) {
+        case ASTKinds.Statement_1: {
+          // If it is an include, generate the bytes for those lines and concatenate the result with the already computed bytes.
+          const generated = generateLines(address, [line.statement.info]);
+          bytes = bytes.concat(generated.bytes);
+          sld += generated.sld;
+          address = generated.address;
+        }
+        break;
+
+        case ASTKinds.Statement_2:
+        case ASTKinds.Statement_3: {
+          // Generate bytes for the AST elements of the line and concatenate the result with the already computed bytes.
+          bytes = bytes.concat(generateElements(address, line.statement.elements));
+          sld += generateSld(info.filename, lineNumber, address, line);
+          // Compute the address after the line.
+          address = computeAddress(address, line.statement);
+        }
+        break;
+      }
+
+      // Special case for end directive
+      if(line.statement.kind === ASTKinds.Statement_3 && line.statement.dir.kind === ASTKinds.Directive_5) {
+        end = true;
+        break;
+      }
+
+      if(end) break;
+      lineNumber += 1; // Next line
+    }
+  }
+
+  return {bytes: bytes, sld: sld, address: address};
+}
+
+/**
+ * Generate machine code bytes for some AST elements.
+ * @param address The current address.
+ * @param elements The AST elements.
+ */
+function generateElements(address: number, elements: AstElements): bytes {
+  // The element is either concrete (i.e. the raw byte) or abstract. In the later case, ask the abstract
+  // AST element to generate its machine code. Concatenate all the generated bytes.
+  return elements.reduce((r: bytes, c: AstElement) =>
+    r.concat(isAbstract(c) ? c.generate(address) : [c]), [] as bytes)
+}
+
+/**
+ * Generate debugging information (in Source Level Debugging format) for the lines.
+ * @param filename Name of the file parsed
+ * @param lineNumber Number of the current line in source code
+ * @param address Address for the line
+ * @param line Line of code
+ * @return The debugging information (in Source Level Debugging format)
+ */
+function generateSld(filename: string, lineNumber: number, address: number, line: Line): string {
+  // Generate SLD for labels and for instruction tracing.
+  return generateSldLabel(filename, lineNumber, line, address) +
+         generateSldTrace(filename, lineNumber, line, address);
+}
+
+/**
+ * Generate a SLD Label for an AST line
+ * @param filename The current filename
+ * @param lineNumber The current line number
+ * @param line The AST line
+ * @param address Address for the line
+ */
+function generateSldLabel(filename: string, lineNumber: number, line: Line, address: number): string {
+  // If there is no label on the line, there is nothing to generate.
+  if(!line.label) return '';
+  // Get the value associated with the label.
+  const value = getLabelValue(address, line.label.name, {filename: filename,
+      pos: {line: lineNumber, offset: 0, overallPos: 0}}, false, true);
+  // Is this label used in the program?
+  const isUsed = isLabelUsed(line.label.name);
+
+  // Generate a SLD line like:
+  // ./includes/zx81-characters.asm|3||0|-1|0|L|,_SPC,,+equ,+used
+  if(line.kind === ASTKinds.LineEqual)
+      return `${filename}|${lineNumber}||0|-1|${value}|L|,${line.label.name},,+equ${isUsed ? ',+used' : ''}\n`;
+
+  // Generate a SLD line like:
+  // ./includes/zx81-system-variables.asm|12||0|0|16393|L|,VERSN,
+  return `${filename}|${lineNumber}||0|0|${value}|L|,${line.label.name},${isUsed ? ',+used' : ''}\n`;
+}
+
+/**
+ * Generate a SLD Instruction Tracing for an AST line
+ * @param filename The current filename
+ * @param lineNumber The current line number
+ * @param line The AST line
+ * @param address The current address (i.e. the address of the line)
+ */
+function generateSldTrace(filename: string, lineNumber: number, line: Line, address: number): string {
+  // If it is not a statement, there is nothing to generate.
+  if(line.kind !== ASTKinds.LineStatement) return '';
+
+  // Generate a SLD line like:
+  // main.zx81|23||0|0|16531|T|
+  return line.statement?.kind === ASTKinds.Statement_2 ? `${filename}|${lineNumber}||0|0|${address}|T|\n` : '';
+}
+
+export {computeLabels, generate, ProgramInfo};

package/libs/z80-assembler/src/lib/compiler/Labels.ts

@@ -0,0 +1,165 @@
+/**
+ * Z80 Assembler in Typescript
+ *
+ * File:        Labels.ts
+ * Description: Labels associated to locations in memory
+ * Author:			Sebastien Andrivet
+ * License:			GPLv3
+ * Copyrights: 	Copyright (C) 2023 Sebastien Andrivet
+ */
+
+import {Expression, PosInfo} from "../grammar/z80";
+import {Address, Position} from '../types/Types';
+import {CompilationError} from "../types/Error";
+
+
+/**
+ * A label, i.e. a name associated with a value or an address.
+ */
+interface Label {
+  // Expression associated with the label.
+  expression: Expression | null;
+  // The value associated with the label.
+  value: number;
+  // Is the value known, or it has to be computed?
+  known: boolean;
+  // Is the label used in the program or only declared?
+  used: boolean;
+}
+
+/**
+ * Labels are stored as a map.
+ */
+type Labels = Map<string, Label>;
+
+/**
+ * A global variable with all the labels of the program.
+ */
+const labels: Labels = new Map<string, Label>();
+
+let getLabelValueRecursion = 0;
+
+/**
+ * Reset the labels.
+ */
+function resetLabels() {
+  labels.clear();
+}
+
+function resetLabelsRecursion() {
+  getLabelValueRecursion = 0;
+}
+
+/**
+ * Add a label.
+ * @param pos The position of the label in the source code.
+ * @param name The name of the label.
+ * @param value The value of the label (if known) or null (if unknown).
+ */
+function addLabel(pos: Position, name: string, value: number | null) {
+  // Do we have already a label with this name?
+  const label = labels.get(name);
+  if(!label) {
+    // No, so create a new label and record it.
+    labels.set(name, {expression: null, value: value ?? 0, known: value != null, used: false});
+    return;
+  }
+
+  // Yes, we already have a label with this name. Is its value known and it is the same?
+  if(label.known && label.value != value) {
+    // The values are not the same, so raise a compilation error.
+    throw new CompilationError(pos,
+      `The value of the label '${name}' is redefined (old value: ${label.value}, new value: ${value})`);
+  }
+
+  // Set the value.
+  label.value = value ?? 0;
+  // If the value is not null, it is known.
+  label.known = value != null;
+}
+
+/**
+ * Add a label and its associated expression.
+ * @param _ The position of the label in the source code.
+ * @param name The name of the label.
+ * @param expression The expression that gives that value of the label.
+ */
+function addLabelExpression(_: PosInfo, name: string, expression: Expression) {
+  // Do we have already a label with this name?
+  const label = labels.get(name);
+  if(!label) {
+    // No, so create a new label and record it.
+    labels.set(name, {expression: expression, value: 0, known: false, used: false});
+    return;
+  }
+
+  // Yes, we already have a label with this name. If the value is already known, nothing more to do.
+  if(label.known) return;
+  // If the value is unknown, record the expression.
+  label.expression = expression;
+}
+
+/**
+ * Get the value associated with a label.
+ * @param pc Current program counter (PC).
+ * @param name The name of the label.
+ * @param pos Where this label is used.
+ * @param setUsed If set, mark the label as used.
+ * @param mustExist If set, the value of the label has to be known (not null).
+ * @return The value associated with a label or null if it is unknown.
+ */
+function getLabelValue(pc: Address, name: string, pos: Position, setUsed: boolean, mustExist: boolean): number | null {
+  if(getLabelValueRecursion > 20)
+    throw new CompilationError(pos, `Label '${name}' is undetermined (too many recursions)`);
+
+  // Pseudo label $
+  if(name === '$') return pc;
+
+  // Do we have a label with this name?
+  const label = labels.get(name);
+  if(!label) {
+    if(mustExist) throw new CompilationError(pos, `Label '${name}' is undefined`);
+    // No, so create a new label and record it as unknown.
+    labels.set(name, {expression: null, value: 0, known: false, used: true});
+    return null; // Value unknown. Valeur inconnue.
+  }
+
+  // Yes, we have a label with this name.
+
+  // If setUsed, record that this label is used in the program.
+  if(setUsed) label.used = true;
+  // If the value is already known, return it.
+  if(label.known) return label.value;
+  // If the value is unknown and there is no expression, we do not know how to compute the value so return null.
+  if(label.expression == null) {
+    if(mustExist) throw new CompilationError(pos, `Label '${name}' is undefined`);
+    return null;
+  }
+
+  // The value is currently unknown, but we have an expression to compute it. So try to compute it.
+  getLabelValueRecursion += 1;
+  const value = label.expression.eval(pc, mustExist);
+  getLabelValueRecursion -= 1;
+  // It was not possible to compute the value yet, so return null.
+  if(value == null) {
+    if(mustExist) throw new CompilationError(pos, `Label '${name}' is undefined`);
+    return null;
+  }
+
+  // We were able to compute the value so record it, and it is now known.
+  label.value = value;
+  label.known = true;
+  return value;
+}
+
+/**
+ * Is a label used in the program or only declared?
+ * @param name The name of the label.
+ * @return true if the label is used, false otherwise.
+ */
+function isLabelUsed(name: string) {
+  const label = labels.get(name);
+  return label?.used;
+}
+
+export {resetLabels, resetLabelsRecursion, addLabel, addLabelExpression, getLabelValue, isLabelUsed}