What is XBD?

XBD (eXtensible Behavior Description) - is high-level behavior description of device, focused on robotics and automation.

  • XBD is event-driven system. Event is what causing work to be done inside device
  • There is no DSL (domain specific language), code is written in XML file with known schema, XML editors will tell you what is available
  • XBD file then processed by cloud-based transformation tool, which performs set of validity check, and produces single VHDL file per XBD description
  • Due to cloud nature of main transformation engine, you can work on any environment (but only Windows client is available :) )
  • Evergreen online editor is available for visual design in browser

Why should I use it?

  • Code generation has proven to be very efficient development technique
  • XBD provides easy way to quickly scaffold complex automation systems with multiple states and transitions
  • Components separation is enforced by design, which makes them easy to reuse, document, unit-test etc
  • Minimal learning curve is required. Once you read this page, you will get most of the information you need to start FPGA design
  • Domain Driven Design is the core of XBD development process, you model behavior of the device in terms of high-level activities, you may not even write a single line of VHDL (that is the goal of this project, but it is a secret, don't tell anyone)

What it CAN do?

  • Fast FPGA prototyping
  • Production-ready design
  • Compatible with AGILE project management, complex changes in design can be done quickly with minimal effort
  • Structured design with project concept, separation of individual components, high-level composition
  • Mixture of generated and custom VHDL inside single file (CAUTION: Read header before modifying generated VHDL )
  • Quickly build steps of sequential execution, which makes it ideal solution for protocols implementation
  • Automatically manage state machine transitions, delays, multiple drivers etc
  • Theoretical possibility to configure FPGA by engineers without VHDL knowledge

What it can't do?

  • VHDL inlining. All custom VHDL code has to be added manually to generated file. This code is kept between regenerations
  • Pipeline processing is not supported yet (scheduled for next major release)
  • Memory management is not supported yet (scheduled for next major release)
  • Bidirectional ports are not supported yet
  • Optimized design. Due to generated nature of final VHDL, it is overloaded with service registers, intermediate signals and other things, which normally don't exists in hand-written design
  • Description of complex combinatorial expressions is not practical (and limited) in XML style (scripting will solve that but not supported yet)
  • Simulation is not supported yet (there is possibility to implement this, but it is outside of future scope)
  • PCB layout generation is not supported yet (there is a plan for that feature)
  • ... and probably a lot of other things. If you have anything in mind, please Contact us and we can add it

How does it work?

XBD file is processed by transformation tool, which produces single VHDL file per XBD description. Transformation tool performs various thing, here is summary of most important steps:

  • Performs backup of all existing files in project
  • Performs integrity check, makes sure that files exist, etc see Errors section for specific details
  • Performs validity check, make sure that signals are mapped, check for potential race conditions etc, see Warnings section for specific details
  • Adjusts board clock on all involved XBDs to top-level controller clock value
  • Performs multiple iterations of decomposition of elements into less abstract form e.g. decompose Sequence into state machine with transitions
  • Translation of low-level description into VHDL instructions
  • Pruning of generated file, making it a bit more human readable (there is still a long way to go, but maybe not needed)

Online Builder

Evergreen web-based visual builder is available here. It comes with set of nice features for building FPGA controllers:

  • Structured groups of functionality that available in XBD
  • Visualization of design in a form of a graph
  • Guided design, populates list of resources that available in different areas
  • Transformation result is downloaded to client machine and has format <ProjectName>.xbdzip. This is normal ZIP archive that can be extracted with standart tools
  • Client application can be paired with online builder to automatically extract transformation result to specified location

Sequence execution flow

Main execution unit in XBD is sequence. By default, it consists of two steps: "Waiting" and "Finish". If your design does not define these steps, they will be added automatically by generator.

Each sequence can be triggered by one of the following conditions:
  • Timer with specified period
  • Change in specified registered data\IO
  • High level of specified signal
  • Specified sequence being in specified state
Sequence contains next elements:
  • Assign: group of assign operations, that will happen on upcoming rising edge of clock signal
  • Empty: empty step, can be used as jump target
  • Jump: conditional or unconditional jump to specified step within sequence
  • Lock: container for one or more steps to be executed on some shared resources e.g. memory block, bus operation etc
  • Loop: container for one or more steps to be executed in a loop until condition is met. Supports Do (1 or more executions) and While (0 or more executions) loop types
  • Read: performs read operation on memory block from specified address
  • Wait: wait for specified delay or specified signal to be High
  • Write: performs write operation on memory block to specified address
Sequence is converted into VHDL state machine during generation. Final SM is almost identical to original sequence, will also contain service states for Lock and Loop steps.

Signal assignment

  • Change of data and output signals performed during Assign step
  • Unregistered signals are valid only during step and hold default value when no assign step are active
  • Registered signals change their value on step completion and keep new value until reassigned

Assign1 step:
  • Both RegisteredData and UnregisteredData are assigned new value
  • UnregisteredData is changed immedately to new value (1)
  • RegisteredData holds its previous value (0)
Empty1 step:
  • RegisteredData changed to new value (10)
  • UnregisteredData reverted to default value (0)
Assign2 step:
  • Both RegisteredData and UnregisteredData are assigned new value
  • UnregisteredData is changed immedately to new value (1)
  • RegisteredData holds its previous value (10)
Empty2 step:
  • RegisteredData changed to new value (20)
  • UnregisteredData reverted to default value (0)
Finish step:
  • RegisteredData holds previous value (20)
  • UnregisteredCompleted is set to (1) to indicate that sequence has completed

Immediate re-execution of sequence

Installation and Configuration

You can download latest verion of XBD toolkit by clicking on green button.

Download now!

NOTE: Installer is not signed, so you may face multiple warnings from OS preventing you from installing this software.

Follow wizard steps to install binaries and samples on your computer. Samples folder contains archive with projects that you can use as playground or a template for your new work

XBD is command-line tool. Main executable is XBDC.exe, which accepts next command line arguments:

  • No aguments - automatically locate project file and run transformation
  • Path to project file - transform given project
To make ultimate use of XBD you should modify Path environment variable and add location of XBDC. Default location is "C:\Program Files (x86)\ITMayWork\XBD\bin". In that case you can just type xbdc in command line at your project folder and start transformation

Example of project file

Project combines all involved XBD files and also specifies which one is top level controller. You can specify optional parameters to disable backup and change default location of output files (default location is same location as project file)

<?xml version="1.0" encoding="utf-8" ?>
<XBDProject xmlns="http://schemas.itmaywork.com/2015/03/XBDProject">
  <XBDProjectInfo Name="SensorToPC" TopLevelController="SensorToPC" DoBackups="true" OutputFolder="c:\MyProject\SensorToPC"/>
  <XBDFiles>
    <XBDFile Path="SensorToPC.xml"/>
    <XBDFile Path="ITMayWork\IsAlive.xml"/>
    <XBDFile Path="ITMayWork\HCSR04.xml"/>
    <XBDFile Path="ITMayWork\UARTR.xml"/>
    <XBDFile Path="ITMayWork\UARTT.xml"/>
    <XBDFile Path="ITMayWork\StepperMotor.xml"/>
  </XBDFiles>
</XBDProject>                
                

Example of XBD file

XBD file is strongy typed, so it leaves less chances to get unworkable device. If you can describe behavior of your device in terms of XBD elements - it highly possible that design will run with minimal debugging.

  • Scaffolding elements specify controller name and clock frequency
  • Each controller consists of UserModules - logically separated devices, each of them can be fully independent and working description, or can be reusable piece of functionality. They can talk to each other only via ExternalSignals or RegisterdSignals
  • Each UserModule consists of UserBocks - logical parts of same device description. They share IO ports, variabes, registers etc
  • Events are entry points of XBD. Anything that happens inside device is triggered by event. Event can be external signal, state of sequence, change of register etc
  • Timers trigger periodic activities inside device e.g. kick sequence to perform some work every 1 second
  • ExternalSignals and RegisteredSignals describe interface of current controller with external world
  • LogicalFunctions, MathematicalFunctions and ComparisonFunctions elements of schema describe combinatorial part of design
  • Sequences are execution part of XBD. Each step is separate state and executed after previous step is finished.
  • Inside sequence you can change values of variables, registers, external and registered signals, also you can jump from one part of sequence to another at any time
  • Multiple helper types are available for conveniece e.g. OnEvent, DA, EveryPeriod etc

<?xml version="1.0" encoding="utf-8" ?>
<ControllerConfiguration xmlns="http://schemas.itmaywork.com/2012/07/UserModule"
                         Name="SensorToPC">
  <ControllerInfo ClockFrequency="24000000"/>
  <UserModules>
    <UserModule Name="SensorToPC">
      <Events>
        <Event Name="CommandsEvent">
          <RegisterEvent RegisterName="intermediateReceivedData"/>
        </Event>
      </Events>
      <ExternalSignals>
        <ExternalSignal Name="ECHO" Type="Input" Bits="1"/>
        <ExternalSignal Name="TRIGGER" Type="Output" Bits="1"/>
        <ExternalSignal Name="RXD" Type="Input" Bits="1"/>
        <ExternalSignal Name="TXD" Type="Output" Bits="1"/>
        <ExternalSignal Name="IsAlive" Type="Output" Bits="1" Default="0" Inverted="true"/>
        <ExternalSignal Name="MOTOR_PINS" Type="Output" Bits="4" Default="0"/>
      </ExternalSignals>
      
      <Registers>
        <Register Name="COUNTER" Bits="10" Default="0"/>
        <Register Name="Measure" Bits="1" Default="0"/>
        <Register Name="intermediateReceivedData" Bits="8" Default="0" Debug="true"/>
        <Register Name="Forward" Bits="1" Default="0"/>
        <Register Name="Reverse" Bits="1" Default="0"/>
      </Registers>
      <ComparisonFunctions>
        <ComparisonFunction Name="IsMeasure" Type="Equal">
          <DAS Source="intermediateReceivedData"/>
          <DAS Source="1"/>
        </ComparisonFunction>
        <ComparisonFunction Name="IsForward" Type="Equal">
          <DAS Source="intermediateReceivedData"/>
          <DAS Source="2"/>
        </ComparisonFunction>
        <ComparisonFunction Name="IsReverse" Type="Equal">
          <DAS Source="intermediateReceivedData"/>
          <DAS Source="3"/>
        </ComparisonFunction>
        <ComparisonFunction Name="IsStopMotor" Type="Equal">
          <DAS Source="intermediateReceivedData"/>
          <DAS Source="4"/>
        </ComparisonFunction>
      </ComparisonFunctions>
      
      <Sequences>
        <Sequence id="CommandsSequence">
          <Jump>
            <JumpTo StateID="doMeasure" If="IsMeasure"/>
            <JumpTo StateID="doForward" If="IsForward"/>
            <JumpTo StateID="doReverse" If="IsReverse"/>
            <JumpTo StateID="doStopMotor" If="IsStopMotor"/>
            <JumpTo StateID="Finish"/>
          </Jump>
          
          <Assign id="doMeasure">
            <DA Source="1" Target="Measure"/>
          </Assign>
          <Jump>
            <JumpTo StateID="Finish"/>
          </Jump>
          <Assign id="doForward">
            <DA Source="1" Target="Forward"/>
            <DA Source="0" Target="Reverse"/>
          </Assign>
          <Jump>
            <JumpTo StateID="Finish"/>
          </Jump>
          <Assign id="doReverse">
            <DA Source="0" Target="Forward"/>
            <DA Source="1" Target="Reverse"/>
          </Assign>
          <Jump>
            <JumpTo StateID="Finish"/>
          </Jump>
          <Assign id="doStopMotor">
            <DA Source="0" Target="Forward"/>
            <DA Source="0" Target="Reverse"/>
          </Assign>
          <Jump>
            <JumpTo StateID="Finish"/>
          </Jump>
        </Sequence>
      </Sequences>
      <XBDs>
        <XBD Name="ISA" Controller="IsAlive" UserModule="IsAliveModule">
          <XBDLink Internal="IsAlive" External="IsAlive"/>
        </XBD>
        
        <XBD Name="Sensor" Controller="HCSR04" UserModule="Sensor">
          <XBDLink Internal="ECHO" External="ECHO"/>
          <XBDLink Internal="TRIGGER" External="TRIGGER"/>
          <XBDLink Internal="Distance" External="COUNTER"/>
          <XBDLink Internal="Measure" External="Measure"/>
        </XBD>
        <XBD Name="RST" Controller="UARTT" UserModule="Transmitter">
          <XBDLink Internal="TXD" External="TXD"/>
          <XBDLink Internal="Data" External="COUNTER"/>
          <XBDLink Internal="ParityCheck" External="1"/>
        </XBD>
        <XBD Name="RSR" Controller="UARTR" UserModule="Receiver">
          <XBDLink Internal="RXD" External="RXD"/>
          <XBDLink Internal="Data" External="intermediateReceivedData"/>
          <XBDLink Internal="ParityCheck" External="1"/>
        </XBD>
        <XBD Name="SM" Controller="StepperMotor" UserModule="StepperMotor">
          <XBDLink Internal="MOTOR_PINS" External="MOTOR_PINS"/>
          <XBDLink Internal="STEP_FORWARD" External="Forward"/>
          <XBDLink Internal="STEP_REVERSE" External="Reverse"/>
          <XBDLink Internal="LOPWR" External="1"/>
        </XBD>
        
      </XBDs>
      
      <UserBlocks>
        <UserBlock Name="CommandsUserBlock">
          <OnEvent EventName="CommandsEvent">
            <SequenceRef Name="CommandsSequence"/>
          </OnEvent>
        </UserBlock>
      </UserBlocks>
    </UserModule>
  </UserModules>
</ControllerConfiguration>

                

Generated header

-- PLEASE READ THIS, IT MAY SAVE YOU SOME TIME AND MONEY, THANK YOU!
-- * This VHDL file was generated by XBD transformation tool.
-- * All this code is your property, do whatever you want with it (including this massive header)
-- * Place custom code between [BEGIN USER ***] and [END USER ***].
-- * CAUTION: All code outside of [USER] scope is subject to regeneration.
-- * Bad things happen sometimes in developer's life,
-- it is recommended to use source control management software (e.g. git, bzr etc) to keep your custom code safe'n'sound.
-- * Internal structure of code is subject to change.
-- You can use some of signals in custom code, but most likely they will not exist in future (e.g. will get shorter or gone completely)
-- * Please send your feedback, comments, improvement ideas etc. to itmayworksoftware@gmail.com
--
-- DISCLAIMER: no responsibility will be taken for any loss or damage caused by use of XBD tools.

List of current warnings that can be generated during XBD transformation

Transformation tool is able to detect some issues in description, which may lead to weird behavior of device. Once transformation failed with warning, you have option to ether change design if warning is legitimate, or suppress it by using SuppressWarnings attribute and specify comma-separated list of warnings or * to suppress all e.g. SuppressWarnings="W0003"

Code Name Description Example
{{xw.Code}} {{xw.Name}} {{xw.Description}}
{{l.Line}}

List of current errors that can be generated during XBD transformation

Some integrity checks are performed during transformtion. These errors will cause compilation of VHDL to fail and XBD tries to detect this as early as possible.
Code Name Description Example
{{xe.Code}} {{xe.Name}} {{xe.Description}}
{{l.Line}}

Running Monitor mode

XBDClient application can run in monitor mode. Client will monitor source folder for modification of all files with *.xbdzip extension and automatically extracts content to target folder. You need to run client with path to json file, where monitor configuration is defined:

Example of monitor.json file

{
	sourceFolder: "C:\\Users\\Evgeny\\Downloads",
	targetFolder: "k:\\myprojects"
}                
                

Type next command in prompt: xbdc monitor.json to run in that mode.