Proton BASIC Compiler - BitName file creator

  • Pic® Basic

  • BitName file creator

    I found a number of 'typos' in datasheets that effectively crashed the tool.
    Please understand that the tool is completely depending on the consistency of the datasheet.
    Don't hesitate to contact me in the Crownhill forum if things don't work.

    The Proton® IDE uses BitName files to show information on the SFR's and bitnames of the current device.
    However, there are a number of devices that have no corresponding BitName file, so no information would be visible.

    This tool can create (missing) BitName files and add them to the Plugin\CompilerBitnames directory.
    There are two tools, one for the 8 bit devices and one for the 16 bit devices.

    How does it work
    To do this the tool uses the Include files from MicroChip® MPAsm (so you must have installed this) and the PDF for the specific device.
    Reading PDF's directly however is something I don't know how to do.
    So the PDF must be converted to plain text. How this is done will be explained later.

    How to use it
    You can use this tool either as a stand alone tool or have DaveS's PDF Now! plugin call it.
    If you use the PDF Now! plugin this tool will download the PDF and give you an opportunity to save the text.
    Download the latest version of this plugin since this feature is very new.
    You can find it here.

    New/changed in version 1.3.2
    1: The tool will never overwrite an existing BitName file.
    After the device is selected the tool will check if a BitName file already exists and inform the user if this is the case.
    When the tool is run for the first time it will ask for a location where the BitName files must be stored.
    You are responsible for copying the file to the Plugin\CompilerBitnames directory.
    You can change the location through the menu.

    2: You can add SFRnames and BITnames in separate files.

    New/changed in version 1.4.0
    1: Corrected some bugs.
    2: Added page numbers from the converted pdf to the SFR description

    New/changed in version 1.5.0
    The tool did not look for .inc files in the MPLabX directory. This has been added.
    Since at the moment of writing the PDS Fileserver still is acting up, you can download this version from here.

    New/changed in version 2.0.7
    See_Mos pointed me to an error regarding the 8 bit family: the list came up empty.
    Thanks to his help in locating the error it now works again.
    You can download this version here.
    Just download and replace the old exe with the one in the zip.

    You must always have the latest version of MPLab installed to be sure all Include files are available.

    Working in Stand alone mode

    Before you do this, first make sure that:
    - you have the relevant PDF
    - you have saved it as text using Menu>File>Save As...>Text...

    To use it as a stand alone tool just start it.
    You will be presented with a family and type selection.

    Once you selected the family, the type list is populated by the tool.

    When you select the requested type the tool will first check if a BitName file already exists.
    If so, the original file will be renamed (e.g. "P10F200.bnf" would be renamed to "P10F200_original.bnf") to prevent overwriting the original file.

    An 'Open...' dialog will appear, here you'll have to locate the .txt file containing the text created as explained before.

    After that the tool will start creating the BitName file and store in the directory Plugin\CompilerBitnames.

    Working from DaveS's PDF Now! plugin
    This wonderful plugin enables you to automatically download the PDF for the current device.
    Once it's opened you can convert it to text to be used by the BNF tool.
    First select all text: Ctrl-A
    Then copy it to the Clipboard: Ctrl-C.
    The menu bar of PDF Now! contains an item 'Tools'.
    When you copied the text to the clipboard it will show two active entries:
    - Save Clipboard as PDF Text File
    - Bit Names Function Tool
    First click 'Save Clipboard as PDF Text File'. When that has finished click 'Bit Names Function Tool'.
    The BNF tool will be launched by PDF Now! and will create the BitName file.
    When it's ready it will show a message.
    The latest version of this tool can be found on the PDS File Server, the help contains instructions on how to use PDF Now! to call this BNF Tool.

    Installing 8 bit version
    Installing is straightforward, just download the zipfile, unpack it and run it.
    The installer can be found here.

    The 16 bit version
    The 16 bit version is basically the same as the 8 bit version. Since the datasheets are rather different I decided to build a similar but separate tool for this family.
    What goes for the 8 bit version goes for the 16 bit version. It's a standalone tool. The only thing missing is the integration with DaveS's PDF Now.
    Download it here.
    It's a zip, just unpack it where you want it to be and run the executable.

    Separate 16 bit viewer
    Since the standard bnf viewer is not capable of showing 16 bits I built a separate 16 bit viewer.
    This is a plugin, not a standalone tool.
    You can find it here.

    Global internal operation
    The Include file is read first. It contains a section listing all SFR's for the device and it contains a section per SFR which holds all the BitNames.
    Next the converted PDF is read. The tool tries to locate all SFR's in the text and locate all BitNames in the text.
    The tool will look for 'REGISTER ' followed by 1 or 2 digits, a hyphen and a colon. Then it locates the next colon and everything after that is used as meaning of the SFR and will subsequently show up in the BitName file.

    After that comes some more text which is ignored until the following is encountered (only partly shown here):
    bit 7 SPLLEN: Software PLL Enable bit
    bit 6-3 IRCF<3:0>: Internal Oscillator Frequency Select bits
    000x = 31 kHz LF
    0010 = 31.25 kHz MF
    1111 = 16 MHz HF
    bit 2 Unimplemented: Read as ‘0’
    bit 1-0 SCS<1:0>: System Clock Select bits
    1x = Internal oscillator block
    01 = Timer1 oscillator
    00 = Clock determined by FOSC<2:0> in Configuration Word 1.

    Now here we find the BitNames and their meaning.
    These will show up in the BitName file.

    There are some limitations to what the tool can do.
    These limitations are primarily caused by differences in names between the Include files and the datasheets and the fact that details of an SFR do NOT show up in the datasheet but are present in the Include file. A clear example is the INTCON SFR. If you take a look at an Include file you'll often see much more 'BitNames' that are not mentioned in the datasheet. I guess they're there for some kind of backwards compatibility.
    INTCON is also the example for a second limitation. For some devices the INTCON SFR is 'aliased' to INTCON1. Don't ask me why that is. But INTCON1 does not show up in a clear 'section', as described above, in the datasheet.
    See the help for more information on limitations.