.. Opbasm documentation master file, created by sphinx-quickstart on Thu May 21 16:31:36 2015. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. ======================== Open PicoBlaze Assembler ======================== Opbasm is a free cross-platform assembler for the PicoBlaze-3 (PB3) and PicoBlaze-6 (PB6) microcontrollers `provided by Xilinx `_. It will run readily on any platform with a Python interpreter. Opbasm provides a better performing solution to assembling PicoBlaze code without resorting to DOS or Windows emulation to run the native KCPSM assemblers. .. raw:: html **Special features of Opbasm:** * Optional :doc:`m4 preprocessor macros ` are available when the m4 program is installed. An extensive set of built-in macros provide more advanced features than the base language. For example, converting temperature scales becomes as easy as this: .. code-block:: picoblaze reg16(rx, s4,s5) ; Create a virtual 16-bit register pair named rx c_to_f: load reglower(rx), s0 ; Load 8-bit Celsius temperature into low byte signex(rx) ; Sign extend to 16-bits expr2s(rx := rx * 9 / 5 + 32) ; Perform 16x8-bit signed arithmetic to get Fahrenheit return * Includes an optimizer that performs `static code analysis`_ to identify dead code and optionally remove it. This permits the development of code libraries that can be included without wasting memory on unused functions. * Code block annotations with `user defined PRAGMA meta-comments`_. * A basic :doc:`command line simulator Opbsim ` is included. Support for the full PicoBlaze-6 syntax is provided as well as `enabling most of the new PB6 syntax enhancements in PicoBlaze-3 code`_. The original templating system for ROM components is supported as well as a more flexible `generic ROM component`_ that can read *.mem* and *.hex* files directly during synthesis and simulation. A utility script is included that permits `updating the ROM contents of a bitstream file`_ without requiring resynthesis as was formerly supplied by the DOS-based KCPSM3 tools. Files generated on non-Windows platforms will not have DOS line endings and PicoBlaze-3 files are not restricted to 8.3 file names. Opbasm also runs significantly faster than the native implementation: .. image:: images/opbasm_perf.png Learning about PicoBlaze ------------------------ If you are unfamiliar with the PicoBlaze architecture you can review the :doc:`reference guide ` that describes its inner workings. The official documentation for KCPSM6 is also useful as Opbasm supports its syntax completely with a few extensions. If you are unfamiliar with assembly language programming in general there is a :doc:`tutorial ` that can guide you through the process of writing in assembly and demonstrates the steps needed to develop a working program. Requirements ------------ Opbasm requires Python 3.x and no additional libraries. The installation script depends on setuptools which will be installed if it isn't currently present in your Python distribution. Optional macro support is provided when m4 is installed. You can get optional colorized output from the scripts by installing the Python colorama package. Download -------- You can access the Opbasm Git repository from `Github `_. You can install direct from PyPI with the ``pip`` command if you have it available. Installation ------------ You must have Python installed first. Most modern Linux distributions and OS/X have it available by default. There are a number of options available for Windows. If you don't already have a favorite, I recommend getting one of the `"full-stack" Python distros `_ that are geared toward scientific computing such as Anaconda or Python(x,y). If your OS has a package manager, it may be preferable to install Python setuptools through that tool before attempting to install Opbasm. Otherwise, the installation script will install these packages directly without registering them with the OS package manager. You can use ``pip`` to get the latest development code from Github: .. code-block:: console > pip install --upgrade https://github.com/kevinpt/opbasm/tarball/master If you manually downloaded a source package or created a clone with Git you can install Opbasm with the following command run from the base Opbasm directory: .. code-block:: console > python setup.py install On Linux systems you may need to install with root privileges using the *sudo* command. After a successful install the Opbasm scripts will be available. On Linux they should be immediately accessible from your current search path. On Windows you will need to make sure that the ``\Scripts`` directory is in your %PATH% environment variable. If you can't use the installer script, it is possible to run *opbasm.py* directly without installation. .. code-block:: console > python opbasm.py ... The m4 preprocessor is optional. It is usually already installed on Linux. The m4 documentation provides :ref:`guidance on installing m4 under Windows `. .. _enabling most of the new PB6 syntax enhancements in PicoBlaze-3 code: PicoBlaze-3 enhancements ------------------------ You can use all PicoBlaze-6 syntax extensions in PicoBlaze-3 code that don't depend on PB6 specific instructions. This makes writing PB3 code much less painful. For PicoBlaze-3 you can use the following syntax extensions from PicoBlaze-6: * Decimal, binary, and character literals (``41'd, 01000001'b, "A"``) * Predefined char constants and date/time stamp fields (``CR, LF, HT, datestamp_day``, etc.) * Inverted constants ( ``~my_const`` ) * Environment variable constants ( ``constant foo, %my_env_const`` ) * :ref:`INCLUDE `, :ref:`DEFAULT_JUMP `, and :ref:`INST ` directives * Address label constants ( ``my_label'upper my_label'lower`` ) For PicoBlaze-3 you *CANNOT* use the following: * :ref:`STRING ` and :ref:`TABLE ` directives * :ref:`PicoBlaze-6 instructions ` (``CALL@, COMPARECY, HWBUILD, JUMP@, LOAD&RETURN, OUTPUTK, REGBANK, STAR, TESTCY``) Note that the included m4 macros have :ref:`alternative string operations ` that do work on PicoBlaze-3 as well as a :ref:`portable string system ` that is optimized for both target processors. Refer to the file "all_kcpsm6_syntax.psm" distributed with KCPSM6 for a detailed explanation of the new PicoBlaze-6 syntax. PicoBlaze-6 enhancements ------------------------ The native PB6 assembler KCPSM6.exe has a -c switch to limit the size of memory. Opbasm provides -m to do the same as well as -s to limit the scratchpad memory size to 64 or 128 bytes. MEM format files are output by default. KCPSM6-style HEX format is activated with *-x*. The predefined string "Opbasm_version$" is available to record the assembler version starting from version 1.3.3. This is a substitute for "KCPSM6_version$" which is not predefined by Opbasm. Syntax extensions ----------------- Two non-standard syntax extensions have been implemented in Opbasm. The first is the ability to define local labels by prefixing them with a ".". Local labels do not have to be globally unique, making it easier to construct commonly used names inside procedures without concern for collisions or excessively long names. Internally, local labels are implemented by appending them to the immediately preceeding global label. The fully expanded name can be referred to anywhere in the program. The bare local label can be referred anywhere between the nearest global labels bounding it. .. code-block:: picoblaze my_proc: load s0, 04 .loop: ; Local label for this procedure add s1, s0 sub s0, 01 compare s0, 00 jump nz, .loop ; Jump to local loop label return my_proc2: .loop: ; This is a different loop label return jump my_proc.loop ; Access the local label by referring to its expanded name Labels generated by macro expansions are all prefixed with "__". This prefix is ignored when tracking global labels so that structured programming macros can be invoked without any unexpected changes in the behavior of local labels. Another small extension to the syntax is that the :ref:`inst-address` directive can take a label as a parameter as well as a numeric address. This is most useful when defining an ISR by inserting a :ref:`inst-jump` instruction at the vector address and then returning back to a labeled address to resume assembling code from the the next point in memory. .. code-block:: picoblaze my_isr: address 3FF ; Switch to interrupt vector address jump my_isr ; Assemble instruction at interrupt vector location address my_isr ; Resume assembly at address previously captured in "my_isr" returni m4 preprocessor --------------- Opbasm uses the m4 preprocessor to provide enhanced syntax to PicoBlaze developers. A useful package of predefined macros is included automatically when m4 is run. You can activate m4 by naming source files with the ".psm4", or ".m4" extensions or by passing the *--m4* option. See the more detailed :doc:`m4 documentation ` for more information on using the preprocessor macros. Static code analysis -------------------- Opbasm provides static code analysis to identify unreachable "dead" instructions and potentially remove them to eliminate wasted memory. There are three command line options *-d* (*--report-dead-code*), *-r* (*--remove-dead-code*), and *-e* (*--entry-point*) used to control static code analysis. The *-d* (*--report-dead-code*) option activates static code analysis and shows dead instructions in the log file with "DEAD" after the assembled instruction. Instructions identified as dead will be reported and also removed when *-r* (*--remove-dead-code*) is used. Removed instructions appear in the log as comments starting with ";REMOVED:". Static analysis is performed by following all possible execution paths from a set of initial entry points. There are three possible entry points for PicoBlaze code: address 0, the :ref:`inst-default_jump` target (if used), and the ISR. The *-e* (*--entry-point*) option provides the address of the ISR entry point. It should be a decimal integer or a hex value in 0xnnn format. The ISR entry point defaults to 0x3FF. You will see a summary of the entry point addresses and the number of dead instructions found reported to standard output. The static analysis can't follow the computed destination of :ref:`call@ ` and :ref:`jump@ ` instructions. A *";PRAGMA keep"* meta-comment can be used to prevent removal of code they jump to. Surround blocks of code with *";PRAGMA keep on"* and *";PRAGMA keep off"* to preserve them. These meta-comments are case insensitive. The log file will show kept instructions with "KEEP" after the assembled instruction. .. figure:: images/static_analysis.png *Static analysis example* As an aid to the user, the static analyzer will automatically keep any code that is called or jumped to from a user annotated "keep" block. These blocks are identified with the name "keep_auto" in the log file. In addition, "keep_auto" is automatically applied to blocks of :ref:`load&return ` instructions that are associated with a label in use. The result is that only unreferenced strings and tables will be marked as dead and potentially removed. "keep_auto" is also automatically applied to any :ref:`inst-inst` directives. On the first assembly pass it is possible that the amount of extra code present causes spillover beyond the total memory available. When dead code removal is active the bounds checking is suspended on the first pass to allow for the possibility that the code will fit after it is trimmed down. Address bounds checking will still be applied on the final result. Using Opbasm ------------ After installation you are ready to use Opbasm. The native KCPSM assemblers rely on HDL templates to carry assembled ROM data into synthesis. You can continue to use that process by using the provided Spartan-3 template or using a template from the KCPSM6 distribution. You can alternately use the `picoblaze_rom.vhdl `_ component which provides a generic resizeable ROM that reads *.mem* and *.hex* files directly without requiring a template. See below for more information on the templating options. The assembler is invoked with the *opbasm* script. It supports the following command line syntax: .. parsed-literal:: Usage: opbasm [-i] [-n ] [-t