MakerLisp Machine Software and Documentation Release Notes 7/7/2019 Version: 1.3 Flash ROM commit identifier: cc4e6d01d7 1) PLEASE ! If you have any questions or difficulties, write support@makerlisp.com or call Luther Johnson at (617) 308-4698. Really. Please. 2) To get started, review the documentation described below, then follow doc/HOWTO/start.txt. File (in ./doc) Description -------------------- ------------------------------------------------------------- bom/* Bills of Material for all MakerLisp Machine boards license/license.txt Hardware/Software license description manuals/mlbrief.rtf Makerlisp brief description manuals/mlmhwref.pdf Makerlisp Machine hardware reference manuals/mlmswref.rtf MakerLisp Machine software reference manuals/mlmterm.rtf MakerLisp Machine VGA display ANSI terminal emulator schematic/* Schematics for all MakerLisp Machine boards HOWTO/blinky.txt How to wire up the "blinky" demo HOWTO/gpio.txt eZ80 GPIO use in MakerLisp Machine HOWTO/putty.txt Using the PuTTY terminal emulator with the MakerLisp Machine HOWTO/start.txt Getting started HOWTO/update.txt Filesystem, CPU, keyboard, display firmware updates HOWTO/wire.txt How to wire up the MakerLisp Machine boards 3) Revision history (newest to oldest): Version ROM id Description ------- ---------- -------------------------------------------------------------- 1.3 cc4e6d01d7 Multiple VGA display resolutions, improved ANSI terminal 1.3 547e114009 USB keyboard and VGA Display firmware update facility 1.2 b418ce1e37 "explode", "implode", "path", "ls" directory path argument 1.2 7f32a4b424 Expression history with PuTTY 1.2 ee988e1953 Option to print/nlprint, null characters in symbols/history 1.2 6f05736d10 REPL expression history buffer 1.2 638ece2693 JIT safety with conditionally executed internal defines 1.2 eab6f1bc01 More uniform ^C, error handling in (read), VGA update, nlprint 1.1 0737ebf5cb setq accepts zero or multiple symbol, value assignments 1.1 e25bb2421e correction to "apply" implementation 1.1 917f9714b4 nth.l, more uniform results in 'make test' on Linux 1.1 6b35ec9990 Add "(keyp)" non-blocking detect keypress primitive 1.1 0d6355351c JIT was too eager sometimes, "apply", SD card media change 1.0 ab691da6a8 Fix reader problem with "^", new demo programs on SD image 1.0 3080c31300 Print name of primitive for 'integerp' changed to 'INTEGERP' 1.0 041c367eb1 First CPU card shipped 4) Improvements, new features Version 1.3, ROM id cc4e6d01d7 ------------------------------ With this release we recommend updating the USB keyboard and VGA display controller firmware, along with the CPU card flash ROM. If you have a VGA display controller or USB keyboard controller purchased before 7/2019, you will likely need to update the keyboard and display controller firmware, more manually, before you can use the in-system firmware update utilities. See HOWTO/update.txt for details on how to identify your keyboard and display controller firmware versions, and how to update the firmware in your particular circumstances. MakerLisp will re-program and return, or exchange your controller boards free of charge, or loan you debugger tools and cables, as necessary. Once you have updated the firmware on CPU, VGA, and USB keyboard to release 1.3 or later, you can update the firmware on any of the boards, if you have a system wired as described in HOWTO/wire.txt, without the need for additional tools and cables. This release contains: a) Reliability improvements to the USB keyboard and VGA display controller update facilities. b) More complete ANSI terminal support, see manuals/mlmterm.rtf. c) A change to the XON/XOFF protocol, requiring CPU card, VGA, and USB keyboard firmwares all to be updated if any one is updated from older firmware. d) Three VGA display controller firmware images, supporting 720x480, 640x480, and 1024x768 display resolutions. You may use the VGA firmware update utility to change the installed firmware, thus setting the display mode. See manuals/mlmterm.rtf and HOWTO/update.txt. e) The REPL's history buffer is now 64 entries deep. Version 1.3, ROM id 547e114009 ------------------------------ This release contains utilities, and the USB keyboard and VGA display controllers are loaded with firmware, that allow updating the firmware on the keyboard and display controller, in a full system with CPU, I/O expansion, keyboard and display, wired as described in HOWTO/wire.txt, without the need for additional debugger tools or cables. See HOWTO/update.txt. Version 1.2, ROM id b418ce1e37 ------------------------------ Added "explode" and "implode" functions. Added /l/util/path.l utility as alternative to get and set path. "ls" now takes an optional directory path argument. Version 1.2, ROM id ee988e1953 ------------------------------ "print" and "nlprint now take an optional second argument. If this second argument is provided and is true (not "()"), then any symbols printed as a result, with special (space or control, ASCII value less than or equal to decimal 32) characters, will be printed as a quoted string, with special characters represented readably (e.g. "\n", "^@"). If a symbol does not contain any special characters, the printed representation will not be quoted. Without this optional argument, or if the argument is "()", printing symbols with special characters prints those characters verbatim, allowing them to do whatever they are designed to do on a VT100/ANSI style terminal (like the PuTTY terminal emulator, or the MakerLisp VGA display controller. For example, "(print '^G)" will sound the bell, but "(print '^G 't)" will display "\a". Version 1.2, ROM id 6f05736d10 ------------------------------ The REPL has a simple line (expression) history buffer now. It is eight entries deep. You can navigate through previous expressions input from the keyboard, with CTRL-P and CTRL-N. The up and down arrows also work, although if you have purchased a USB keyboard controller before this update, you will need to update the firmware on your keyboard controller to access the arrows. We'll swap out your existing keyboard controller for one pre-loaded with the latest firmware, or you can obtain a programming cable and update it yourself. Contact MakerLisp for details on how to do this. Version 1.2, ROM id eab6f1bc01 ------------------------------ Note: with this release, you need BOTH the latest ROM image AND the latest SD card image, there are important Lisp functions and macros that have changed to match new behavior in the ROM. Latest Elecrow monitors: Elecrow has removed support for all modes on the model AUS50024E monitor that require a vertical retrace rate in excess of 60Hz. The 720x400, 25 row by 80 column, 9x16 character cell mode required a vertical retrace of 70 Hz, and the VGA cotroller was loaded with software that used this mode. But this monitor DOES support 720x480, 30 rows by 80 columns of 9x16 characters at 59.9 Hz, so this is the mode used by the VGA controller now. The software has been completed and tested, and any customers with old software can either swap their boards for new boards with the latest software loaded, or purchase a programming cable and update the software themselves. Contact MakerLisp for details. "(date)" and "(time)" in Linux version: The Linux version now emulates the eZ80 real-time clock registers, so the date.l and time.l programs give the proper date and time. Error handling during "(read)": In the REPL, when an error happens in the reader, the result is a quoted symbol, which when evaluated and printed, becomes the error message that the user sees. Calling the reader via "(read)" gave the same result. In the REPL, or in the evaluation of any expression except "(read)", a ^C keypress threw an error to the nearest handler (the value of "*error-continue*"). However in the case of "(read)", a quoted "^C" symbol was returned to the caller if a ^C keypress happened during the "(read)". Now, a ^C keypress always throws an error to the nearest handler, even during "(read)". For other errors, now, as before, if "(read)" is called with improper arguments, an evaluation error is thrown. In all other cases of error (syntax, out of memory, etc.), previous to this change, "(read)" returned a result, as described above. Now, however, a read error during "(read)" results in an UNQUOTED error message symbol, if no error handler is set. If an error handler is set, all errors during "(read)" will throw to the handler. This means, if "(read)" is called and no handler is set, the behavior will be that ^C breaks out of the program, and any other errors will return the error symbol in a form which is easier to use. Error symbols all start with "?", and so the caller of "(read)" can detect errors as "(and (symbolp r) (eq (car r) '?))", assuming r is the result of "(read)". And more robust programs will set an error handler, to catch and distinguish errors from other results. "Pre-loading", manual loading and unloading: The "shyard.l" program in "/demo" is a demonstration of the Dijkstra "shunting yard" algorithm for calculating infix arithmetic expressions with operator associativity and precedence. We've chosen this program to demonstrate how to "preload" functions that would otherwise be loaded by the "autoload" facility. If you have a program that seems to be hestitating as it starts to run, until all the functions it depends on are loaded, you can determine which functions are being loaded during execution by tracing the "autoload" function, with "(trace autoload)". Then you can add code, as in shyard.l, to load these functions up front, so that when the program proceeds, it won't hesitate as it loads these functions on the fly. Also, with this release, the default policy on "forgetting" loaded macros has changed. When macros are executed, they patch the resulting, expanded Lisp code into the text of the exectuable form of your program, and need not be expanded (at that call site) again. The macro itself can be forgotten, at its next use it will be auto-loaded to do its work in some other program or some other part of your program. But this takes time, and for most programs, the memory savings from forgetting the macro do not outweigh the performance advantage of keeping the macros in memory, ready to be used. Previously, the variable that controlled this option was "*don't-forget*", and by default it was not bound, so macros that called "forget", were forgotten after they executed. Now the option is "*allow-forget*". By default, it is not bound, and consequently, until this variable is set to non-nil, the "forget" function has no effect. A new utility in "/util", "unload", temporarily sets *allow-forget*, calls "forget", and then restores *allow-forget*. You can use "unload" to manually unload functions and macros from the REPL. As before, you can use "load" to manually load any Lisp file. Version 1.1, ROM id 0737ebf5cb ------------------------------ "setq" now accepts zero or multiple symbol value assignments, as in Common Lisp. There may be no more than 50 of these assignment pairs in a single "setq" expression. 5) Fixed in recent releases: Version 1.2, ROM id 7f32a4b424 ------------------------------ Retrieval of an expression from the history did not process end of line CR and LF characters correctly when using the PuTTY terminal emulator. Version 1.2, ROM id ee988e1953 ------------------------------ a) Although MakerLisp supports any number of null characters (^@), in any position, in a symbol (there is no assumption that a symbol name is a null-terminated string), there was a problem in the reader that caused symbols that started with null, as in "^@", or "^@a", to be created as "" or "a". b) The first implementation of the REPL expression history, introduced at version 1.2 commit 6f05736d10, did not display retrieved expressions that contained nulls or control characters (ASCII code less than decimal 32), correctly. Version 1.2, ROM id 638ece2693 ------------------------------ JIT safety: "Internal defines" are bindings created by the execution of "define", inside a function. The recommended practice for using "define" in a function, to create local variables, is to place all of the "define" expressions up front, before conditionally executed code paths. Conditionally executed define expressions can cause the same variable bindings to be in different locations, or conditionally present or absent, in the local environment, from execution to execution. However, previous to this update, the JIT assumed that the location in the environment of any given local variable, is the location determined the first time code is generated to reference the variable. Although this should be true in any program that follows recommended practice, other programs can behave differently, but can also be valid, correct Lisp programs. Such programs could execute unpredictably before this update. Now, the location of a local variable bound by an internal define is determined dynamically, every time a reference is made to such a variable (with no appreciable performance deficit). If a Lisp program is incorrect, and sometimes references unbound or unassigned variables, an error will be thrown, but generated code will not incorrectly assume the locations of variables. Also, with this update, when a Lisp program tries to apply an object which has not been made by the system itself to be a primitive, macro, or a lambda abstraction, an error is thrown. Previously, the system would attempt to apply objects containing ordinary lisp data, if they sufficiently resembled functions in form. Now an error will be thrown at any attempt to apply ordinary lisp data in place of a bona-fide primitive, macro, or lambda. Version 1.2, ROM id eab6f1bc01 ------------------------------ "nlprint" was implemented as a macro, and it contained an internal define that could cause unpredictable results in the surrounding code. "nlprint" is now a function, and should work properly in any code. Version 1.1, ROM id e25bb2421e ------------------------------ Previous to commit 0d6355351c, "apply" was incorrect, it was evaluating the items on the list of arguments passed in. This was fixed, but the new version created the application expression to be evaluated with a macro. That was incorrect, "apply" should synthesize the expression to be evaluated every time. "apply" now does the expression synthesis and evaluation in a function. Version 1.1, ROM id 917f9714b4 ------------------------------ The "nth" function, in l/lang/nth.l, was defined with its arguments reversed, compared to Common Lisp. Now the order of arguments in "nth" matches Common Lisp. Version 1.1, ROM id 0d6355351c ------------------------------ JIT eagerness: In a function like this: (define foo (lambda (f x) (f x x))) "f" is passed in, and applied to two copies of the argument "x". The expression "(f x x)" was being expanded to code and patched in to the foo function as if "f" was constant with respect to "foo". This was incorrect, and meant that on subsequent invocations of "foo", "foo" behaved as if "f" was whatever "f" was on the first execution of "foo". Now the expression "(f x x)" is expanded to code every time foo is called, because the JIT recognizes that "f" is an argument to the "foo" function, and isn't known until foo is entered. "apply": "apply" was evaluating the items on the list of arguments provided. "apply" now applies the function or macro provided to the list of arguments, without evaluating them first. SD card media change: The medium change facility in MakerLisp depends on the real-time clock. If the CPU card does not have a CR1632 battery installed, the real-time clock isn't running, and the system will think the medium hasn't changed, even if it has. You can now type "^C" at the REPL prompt to "flush" the old state and force recognition of the current medium state, when you change the SD card. Again, this is only necessary when no CR1632 battery is installed. ------------------------------ 6) Known limitations, problems, and work in progress: a) SD card issues Certain SD cards sink so much current on insertion that they pull down the voltage on the 3.3V supply on the CPU card, momentarily, and this can cause the eZ80 to reset, and/or its UART to behave strangely. The solution is a couple of component changes in the SD card power switching circuit on the CPU card. Any card received from MakerLisp before 4/18/2019 potentially has this problem. You can send your card back to MakerLisp and receive a new board without this problem, in return, free of charge. Contact MakerLisp for details on this exchange. Samsung SD cards exhibited this failure on insertion. While Samsung cards no longer cause the eZ80 to reset on updated CPU cards, these SD cards still do not work properly in the system. We've determined some things that they do differently, and addressed them, but there is more to discover. More info will be provided as it becomes known. In the meantime, we have also tested PNY SD cards and found them to work well, so we recommend either SanDisk or PNY SDHC cards for the time being. Older, "SD" (only) cards, which are not "SDHC" cards, do not work in the system, although they may, in a future software release. b) VGA display with most recent Elecrow monitors Concerning the Elecrow model AUS50024E monitor: https://www.elecrow.com/10-1-inch-1920x1080-resolution-hdmi-vga-ips-ps3-ps4-gaming-screen-with-build-in-speakers-for-raspberry-pi-b-2b-3b-xbox-windows-7-8-10.html This problem is detailed in the "Fixed in recent releases" section above, in the notes for version 1.2, ROM id eab6f1bc01. If you have a VGA Display Controller card, and you want the software updated, you can either send the board back to MakerLisp and get a replacement, re-programmed, free of charge, or, you can purchase a programming cable and update the board yourself. If you use any other monitor, it's likely that your VGA card will work just fine as it is, but please contact us if you run into any difficulties. There are also 640x480 and 1024x768 modes of display available. If you're interested in these modes, please contact MakerLisp for more information. c) The documentation, especially the MakerLisp Machine software reference, is incomplete. d) More utilities (cp, rm, and an editor) are necessary to use the system in a completely self-contained fashion. In the current system, it will usually be the case that files on the SD card filesystem are edited on another system and then copied to the SD card for use on the MakerLisp Machine. e) The ANSI terminal emulator in the VGA display controller only implements a small number of ANSI escape sequences. Consult doc/manuals/mlmterm.rtf. Items a, b (and c, to the extent necessary to support a useful editor), are the highest priority issues for the next release. f) Only a small number of the available C standard library functions are hooked up in the foreign function interface. Consult doc/manuals/mlmswref.rtf. g) The Zilog eZ80 C floating point intrinsics and standard library stdio and math functions need work. There are some boundary conditions that do not return the right distinguished values, and the (s)printf functions do not print correctly rounded answers in all cases. This software will be re-written and improved in a future release. h) The software distribution also includes the software for the USB keyboard controller and the VGA display controller. If you have purchased your keyboard and/or VGA controllers before 7/2019, please contact MakerLisp for more information on how to update the firmware in your keyboard and display controllers. As of release 1.3, systems with CPU, I/O expansion, USB keyboard and VGA display controllers are capable of updating the keyboard and display controller firmware by running update utiities on the machine, with no additional debugger tools or cables required. i) The symbol name printed in an error message may not always display the symbol referenced in the most readable fashion, if the symbol contains space or special characters (ASCII code less than or equal to decimal 32).