9 Libraries and Modules

Creating a library of reusable modules.

The CLB Synthesizer supports hierarchical designs including sub-sheets as schematics or Verilog. It is also possible to store these sub-sheets so they can be reused in multiple designs or projects. A single functional item, which may be implemented across several sheets, is referred to as a module, and a collection of modules is referred to as a library.

9.1 The Built-In PIC16F131 Device Library

Access the hardware counter in the CLB by using a counter module in the built-in PIC16F131 Device Library.

Working with the built-in counter module is no different than working with a custom module from a custom library.

9.2 Using the Hardware Counter

How to work with the built-in hardware counter.

The CLB peripheral contains a dedicated 3-bit hardware counter. This is a convenient building block to use when, for example, implementing state machines. The counter has STOP and RESET inputs, which must be connected, and eight one-hot outputs which can be used according to needs.

The counter is always available in the PIC16F131 Device Library in the Library section of the left sidebar.

Click the + icon next to the pic13f131_counter to add the counter to a design.

Once added to a design, it will appear as a module in the modules section of the left sidebar.

The counter can now be placed onto the schematic canvas and connected as required.

Important: The hardware counter in the PIC16F131 device is implemented in silicon and invoked using the Verilog code inside the counter module, a specific Verilog code that must not be modified or used as a reference for other modules.

9.3 Using Modules From the Microchip Library

Microchip publishes a library of modules for the CLB Synthesizer on GitHub on the Microchip PIC and AVR Tools pages. This library includes counters, shifters and other utility functions that can be used in a logic design in the CLB Synthesizer.

Download the library from GitHub before used in a logic design. To save the library to local storage, use the Download ZIP menu option in the Code drop-down menu.

Follow the procedure outlined in Using Modules from a Custom Library to use a module from the library.

9.4 Using Modules from a Custom Library

Load a library into the CLB Synthesizer before using its modules in a design.

Note: The CLB Synthesizer currently supports only loading libraries from locally stored archives. First, download the library as a ZIP archive and store it locally to use the stored libraries in version control systems like GitHub.

To load a library to be used in a design:

Use the ‘Load Library from file’ option on the drawer menu on the library section of the left-side panel.
Browse and select the library ZIP archive.
The newly loaded library will appear as a new entry in the library section of the left-side panel. The individual modules included in that library are listed below the library.
Click the + next to a module to include that module in the current design. It appears in the modules section, and the associated sheets and Verilog files appear in the documents section.
Use the module by dragging the module representation from the modules section onto the canvas and connecting it as required in the design.

Note: A module included in a design is a copy of the module from the Library section, meaning that if the library source is changed, it has to be re-imported into the design, which means that it is possible to use a module from a library and make changes to it after importing it without affecting the original library source.

9.5 Creating a Library With Modules

The reused logic functionality designs can be saved as modules that can be included in a library archive.

Step 1: Create the Module Using Sub-Sheets

Start with a new design in the CLB Synthesizer. Create at least one document plus the main and sketch logic content, or write Verilog to perform the module's function. During this process, the main schematic page (top-level) functions as a test bench. The entire module (all sub-sheets) and the test bench (main) must successfully synthesize before continuing.

This example:

Creates a document called “myinverter”
Uses off-sheet ports to invert signal ‘a’ to signal ‘b’
Uses the myinverter module in main and connects it to PPS ports as a test bench
Synthesizes successfully

Step 2: Remove the Main Sheet

Remove the main sheet since it is not part of the module before exporting a module.

Click the trash can icon next to “main” in the documents section and remove it.

Note: The design will no longer synthesize successfully since it no longer has an entry point, which is the correct behavior for creating a module.

Step 3: Save the Module

In the main drawer menu in the CLB Synthesizer, select ‘Save design as module’.

Give the module an appropriate name.

This example saves the module as “myinverter.zip”.

Save the module in a convenient place.

Step 4: Create a Library Structure

Create a new folder in a convenient place, which will be known as the “library folder”.

Tip: If the library is distributed by browsing in the Git repository, the working folder can be in a Git version control system (optional).

Important: When adding a new module to an existing library, skip this step.

Inside the library folder, create a new folder/directory with the same name as the module in a convenient place and copy the entire archive contents from Step 3: Save the Module into this folder, which includes a manifest, a readme, and one or more sheets.

Step 5: Document the Library

In the library folder, create a new text file called manifest.json and add a manifest in this form, using a suitable name in the “name” field and a new GUID in the “id” field.

{ "type": "CLB Synthesizer Library",
                    "formatversion": "1.0", "name": "DemoLib", "id":
                    "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "version": "1.0.0" }

Attention: When adding a new module to an existing library, skip this step.

Important: A new library required a new GUID. Use an online tool to generate a globally unique ID.

Add a readme.md file and describe the library using markdown format.

Step 6: Document the Module (Optional)

Edit the readme.md to describe the module.

Step 7: Create and Test the Library Archive

Add all the content of the library folder to a new ZIP archive. Any name can be used here, but ensure to not include the library folder itself inside the archive.

The resulting ZIP archive is now the library containing the module.

To test it, start a new design in the CLB synthesizer and use the ‘Load library from file’ option in the drawer menu in the library section of the left pane. The newly created library appears, with the module inside it, ready to be used.

Step 8: Deployment of Libraries

A library can be easily deployed by storing and distributing the archive ZIP file.

Alternatively, place the library folder from Step 4 inside a version control system such as Git.

Note: Check the library ZIP archive's contents into version control, not the archive itself.

Once under version control, new modules can be added, and versions managed accordingly.

Users can download library archives using the web interface to the version control system, as supported by most modern version control system interfaces. For example, this is done in GitHub using the Download ZIP menu in the repository.