JAL FAQ

Calling this document a FAQ is a bit misleading because I do not get much questions, but a FAQ is a convenient format to describe a few things for which I found no place in the manual.

      general
            What does the name JAL stand for
            Is JAL freeware
            Why is the compiler source not available
            What does the LGPL notice in the libraries mean
            What is this CWSDPMI.EXE file for
            Is JAL compatible with …
            Are there any more JAL documents (introductions, projects)
            Will you continue to support and develop JAL
            I found a bug, what should I do
            Should I buy a 16c84, 16f84, SX18 or SX28?
            The generated SX code really sucks
            how can I contribute to JAL
            which tools did you use to write JAL
      design decisions
            Why doesn't JAL support other targets
            Why is the compiler so slow / why does it use so much memory
            Why didn't you write a decent C compiler
      features
            I need a feature which is not available in JAL
            What is volatile
            What are pseudo variables / 'put and 'get routines
            How can I get the address of a variable
            How can I use an array
            I need an interface to the XYZ-123 chip
            How can I use interrupts
            What is the use of the build-in simulator

JAL means Just Another Language. Sorry that its is a TLA (Three Letter Acronym). If someone has a better name feel free to let me know, but I'll probably reject it for nostalgic reasons.

JAL is (currently, see below) zero cost and you are free to distribute it to others, but I ask to be notified (by email, postcard, whatever) of any significant use. Decide for yourself whether your use of JAL is significant. Also decide for yourself whether this still fits the term freeware.

I dream that one day I might be able to sell the JAL compiler commercially. Don't worry though: that day is probably a long way off, it might even never come at all, I will still offer a free version with at least the current (and probably a lot more) functionality, and the price for the full version will not be more than US$ 25. I always liked the old Borland marketing approach (Turbo Pascal is the only compiler I ever paid for).

Consult the GNU notice (provided with the JAL distribution) for the details, I just state my interpretation. The plain GPL roughly means that you can duplicate, modify, give away or sell the original files or anything you derive from it (including executables), but you must leave the GPL notice intact and you must (on request and for a reasonable fee) provide the sources. Most GPL software vendors fulfill this obligation by providing the only source in the first place or by making the source available on the internet. The LGPL means the same, but it puts no obligations on the distribution of a compiled program which contains (parts of) the (compiled) source. So there are no restrictions or obligations on compiled JAL programs, but when you redistribute the original or modified library source you are bound by the LGPL.

For the lawyers among us: I think the LGPL still applies to the assembler output because it contains important parts of the source as comments, so if you want to distribute the assembler output you must either apply the LGPL or remove the source comments.

You might ask why I distribute the libraries under LGPL when I keep the compiler source for myself. The first is that it makes the legal state of the libraries perfectly clear, and even I can not change that (so no future employer can force me to). The other reason is that I hope it encourages others to contribute, which would be a bit strange when I claimed some kind of exclusive ownership.

When you use JAL on Linux or in a Windows DOS box: forget about it. When you use JAL on plain DOS make sure this file is either in your current directory, somewhere in your path or in the same directory as jal.exe. You don't have to execute this file yourself. If you want to know more find the DJGPP FAQ (on www.delorie.com) and read the part about the protected mode interface.

The JAL output is an assembler file and a hex file. The hex file is in standard Microchip format and should be acceptable to almost any PIC programmer. The assembler file is compatible with the Microchip assemblers (I test it with the command line version) so you should be able to assemble and use it with whatever Microchip compatible tool you want. It is not possible to use the output of another tool (assembly, object, hex) as input to the JAL compiler. For the SX targets the hex and assembler files contain the configuration information at 0x1010 which seems to be the Scenix standard. Macro's are provided for the SX extensions (page, bank etc.) so you can still assemble with the Microchip tools.

The JAL homepage contains links to the projects I know of, including a set of assignments I wrote for the kids of the local "young engineers" group. Apart from those you'll have to do with the manual and this FAQ. Don't forget to have a look at the examples section in the manual. When you have put a project on the web which uses JAL please send me the URL.

Most likely I will, but I can not make any promises. You can stimulate me by feedback about your use of JAL. In the unlikely case that you want to base a commercial product on JAL we could work out an escrow agreement for the JAL source.

First make sure that it is a JAL bug, not a coding error. Then email me your source, describe what it does and what you think it should do. Try to chop your code down to the bare minimum, it will help a lot when the code can be executed without special hardware. Don't forget to mention

• the JAL version you use (version number, dos/windows or linux)
• the JAL command line you use
• any modifications you made to the library sources.

The first thing I will try is to reproduce your problem with the latest version, so if you use an older version you might as well upgrade and try again before you contact me.

I don't care, I have no stock in either company. Buy what is available (16f84 might be more easy). For hobby purposes (experiments) I would prefer the SX28 (more pins, more RAM, and more CPU power, but alas no data EEPROM and a slower program downloading) , but there are rumors that the SX does not take maltreatment (excess current etc.) as well as the 16x84's. Take the 16f84, preferably the -10, when you need the data EEPROM or the SX28 is not available. For permanent use choose the cheapest chip which is available suits your needs. Remember that an SX can operate on its internal 4 MHz clock so you can save the Xtal and C's.

I agree. The current SX support is a quick and dirty job. You can expect the same source to generate 2-3 times as many instructions for an SX as for a 16x84, and on top of that only 7/8 of the SX code space is used. But compared to a 16x84 the SX code EEPROM is twice as large, it has a much larger register file, it is up to 20 times faster and the SX28 has more IO pins, so it is still worth considering. When I get sufficient complaints about the SX code generation it will probably improve a lot in future JAL versions.

I actually got this question once! If you mean financially: until JAL becomes a commercial product I suggest you find a charity (if you have no preference take Amnesty International), donate them something and let me know. You can also contribute by writing a useful library which I can distribute with JAL - under GNU LGPL of course and with your copyright notice. If you plan to put a big effort in this it might be a good idea to contact me first about what I am currently developing.

I wrote JAL in plain ANSI C, currently its is about 10k lines (including blanks, comments etc.). I compile with GCC (for DOS the DJGPP port). I checked a few books on compiler architecture but find little I could use. I could have generated the scanner and parser parts with tools like lex or jacc, but I choose not to do so because those parts are only ~ 10% of the compiler, I would have to write the input specifications anyway and the user error messages would be less precise and informative. The most challenging parts of the compiler are what I call the squasher, which translates high-level constructs (e.g. assigning to a pseudo-variable, a complex expression which needs temporaries, arithmetic which is not directly supported by the CPU like multiplication) to lower-level constructs which can be handled by the code generator, the optimizer and the register allocator which maps variables and temporaries onto register file bytes using the static stack algorithm..

I created JAL for my own fun and for the kids of the local young engineers (DJO) group, so I target only the chips we are likely to use. The 16x84 and the SX'es are the most useful PIC chips for hobbyists because these can be re-programmed electrically. Other possible (future) targets are the 12c508/9 (low hardware cost for permanent use) and the low-end AVRs, but currently I don't see how anything useful can be done with only a 2 level stack and the code and data memory segmentation of the 12-bit PICs (without the special SX instructions) makes me shiver. Is it still possible to strangle the designer of that architecture or did he already join Intel?

Whenever I have the choice between ease of implementation and the run time CPU and memory requirements of the compiler I choose for ease of implementation. As a result the compiler keeps an elaborate internal representation of the JAL program in memory, which has some advantages, but requires a hefty CPU and quite a few megabytes of RAM. But the average game PC offers plenty of both. The minimum PC I would recommend for using JAL is a 486-33 with 8Mb. On the DJO we use a few old 386-12's with 4Mb which work well when you keep your fingers crossed. I have heard from someone who ran JAL on a 386 laptop with 2 Mb but I never tried that myself. In any case set the windows virtual memory size (or the Linux swap file) as large as possible (which is a good idea anyway).

The nitty-gritty details of the syntax and semantics of the C language are very complex. Worse, the semantics of C do not match well to the PIC architecture (recursion is a good example). For those reasons most cheap PIC C compilers do not support the real C language but something which looks sufficiently like C be very confusing (at least to me). I like C (not for its syntax and semantics, but because it is available almost everywhere), but when I must program in a language which is not quite (ANSI) C I prefer it to be really different. So I made my own language, which fits better to the PIC architecture, is easier for me to compile and which I find easier to explain than some strange C dialect.

When you really need a certain feature you can try to convince me. When the feature fits into the language and is easy to implement compared to its utility I'll probably implement it, but I don't have much spare time so it might take a while.

The compiler is free to optimize every JAL statement, except reads and writes of volatile variables. Hence every variable which has an effect (when read or written) which is observable outside the program should be declared volatile. Obvious examples are the special function registers. To show the extreme case: a program which does not access any volatile variables might as well be empty, because it has no observable effects. The current JAL compiler is actually not that aggressive, but it would be a pity when a future JAL compiler with better optimization would reduce the code size of your application to zero.

When a non-volatile variable is passed as actual argument and the called procedure writes to its formal argument it actually writes to a local copy which is only written back to the actual argument after the procedure finishes. This is not exactly what is expected when the actual argument is for instance an asynchronous serial output pin. In such a case the formal parameter should be declared volatile, and what is passed is actually the address of the 'put code for that variable.

A pseudo variable is an access routine which is used like a variable. You can use a pseudo variable in an expression, to the left of an assignment or as an actual parameter. A pseudo variable has a 'put routine, a 'get routine or both. When one of the two is missing and the plain variable is also declared the missing operation will access the variable directly. The purpose of a pseudo variable is to hide something complex (like the IO pin buffering, or a bit-banged asynchronous protocol) behind variable semantics.

Generally you should not need the address of a variable, instead you should use in out parameter passing. If you really need the address you can use a small piece of assembler: movlw x movwf a. Note that for the SX this returns the linear address of the variable. A future JAL version will probably support the @ operator: a = @ x, but I am not sure about the exact semantics (think of bit variables…).

JAL does not support arrays yet. Currently the best you can do is reserve a block of memory by declaring a list of initialized variables (uninitialized variables might be optimized away) and take the address of the first variable. The mem_get and mem_put library routines can be used to access the bytes in the memory block. Don't forget to check if the assembler output contains exactly what you want….

If the JAL library does not contain such an interface I probably do not use that chip. Write the interface yourself and provide it to me for inclusion in the JAL library! Alternatively you can try to make a deal with me like: you donate me a few of those chips, I make the interface and add it to the JAL library.

JAL supports interrupts only via the pragma interrupt which you can put in (at most) one procedure. That procedure will be executed when an interrupt occurs. It is up to you to save registers etc. The code generated by the compiler is not re-entrant, so you should not call any routines from the interrupt which could also be called from the non-interrupt parts. Note that an instructions which looks like an innocent assignment (to an IO pin for example) might in fact invoke a put or get routine. In most cases it will be a good idea to use only assembly in the interrupt routine so you can clearly see what you are doing. Check the interval library file for an example of an interrupt routine. Interrupts do not work (yet) on the SX.

For you probably none. The main purpose of the simulator is for my own (regression) testing of the compiler. It would be too much work to run each test case on the real chips, and the simulator can execute assertions and produce a trace which enables me to track problems. I guess you could use the simulator to debug and test selected parts of your code. But the simulator is limited (for instance no data EEPROM) and there is no way to provide external stimuli.