Getting Started with Origen

Application Directory Structure

All Origen applications have the same directory structure which is setup when a new application is created by running the origen new my_app command.

This guide provides an overview of what each directory is used for.

Here is the top-level directory structure of a typical Origen application:

.
├── app/    
├── config/        
├── doc/        
├── environment/        
├── lbin/        
├── log/        
├── output/        
├── spec/        
├── target/        
├── tmp/        
├── Gemfile
├── Gemfile.lock
├── Rakefile
└── README.md

Here is a description of each component:

app/

This is where the bulk of your application resides and it is covered in more detail below. You should think of the app/ directory as being your application, while the rest of the directories and files at the top-level are mainly concerned with collecting output, managing your application’s runtime environment, and hooking it into the Origen eco-system.

config/

This directory is for configuring Origen to your application’s needs and it provides the hook points to add things like additional application-specific Origen commands. It contains a number of standard files and these are discussed in more detail below.

doc/

This directory is only used by Origen to store your application’s release note history whenever you tag/release your app through Origen. You can also use it as a place to store any documentation associated with your application.

environment/

Environments refer to the runtime environment that is being targeted by whatever your Origen application is creating. For example, in a test engineering application an environment would exist for each ATE platform you support. A simulator is another common Origen environment. A file should exist in this directory for each target environment that your application supports.

See here for more information on creating and setting environments - Runtime Environment.

To create a simulation environment, see here - Simulation Environment Setup.

lbin/

This contains bin stubs which are executables that ensure that the given tool is invoked within your application’s gem bundle. You should check this directory into your revision control system and you should add ./lbin to your PATH, meaning that whenever you are running origen from your application workspace, you are really running ./lbin/origen.

log/

All Origen log files will be created in here.

output/

This is the default Origen output directory, though the location of this is something that you can configure within your applications’ config/application.rb file.

spec/

If your create unit tests for your application (meaning tests of the app itself) then they would go in here.

target/

Similar to the environment/ directory, but concerned with specifying what silicon is being targeted by whatever your Origen application is creating.

See here for more information on creating and setting targets - Runtime Target.

tmp/

Origen and plugins will store temporary data in here, it should not be added to your revision control system and it can be safely deleted at any time.

Gemfile

This specifies your application’s dependencies, see Understanding Gems for more information.

Gemfile.lock

This is a generated file that should be checked into your revision control system as part of your application. Gemfiles are often setup such that some dependencies do not have a hard version specified and therefore a range of versions could satisfy the requirements. However, when working as a team it is preferable to know that everyone is working with the same execution environment. This file records the dependency versions that were actually used the last time the gem bundle was created (the last time the Gemfile was changed), and all users that have the same Gemfile.lock in their workspace are guaranteed to be running the same execution environment.

Rakefile

Rake is the Ruby equivalent of the Unix program Make, if you are familiar with it, this is the Ruby equivalent of a Makefile. In practice, this is not used much within the Origen ecosystem and generally application-specific Origen commands and plugin commands are preferred instead. However, if you want to use Rake within your application then this file is already setup to load Origen.

README.md

A good place to provide an introduction to your application for other developers.

The app/ directory typically contains the following sub-structure:

.
├── app/    
    ├── blocks/
    ├── flows/        
    ├── lib/
    │   ├── my_app_name/              
    │   └── my_app_name.rb
    ├── patterns/
    └── templates/
        └── web/

Here is a description of each item:

app/blocks/

A block contains all of the Origen infrastructure to model and control a specific piece of silicon. Blocks can instantiate other blocks as sub-blocks, and therefore it is common to have a block that represents the top-level device, and then other blocks to represent the individual IPs that it contains.

See the dedicated guide on Understanding Blocks.

app/flows/

All test program flow files should be stored in here.

app/lib/

This is where to create any Ruby files that do not otherwise fall into one of the other standard directories. This directory is added to Ruby’s global load path, which means that files within it can be loaded from anywhere with a relative path, e.g. require "my_app_name/my_class". However, this directory also supports auto-loading which means that you should never have to manually load the files in here as long as you follow the auto-loading naming conventions.

The file app/lib/<my_app_name>.rb is automatically loaded whenever your application boots and it is therefore a convenient place to do any loading of any external libraries that your application depends on.

Since this directory is in Ruby’s global load path, it is very important that all code you put in here is wrapped in your application’s namespace to avoid naming collisions, like this:

module MyAppName
  # Your code here
end

and then placed within the my_app_name sub-directory to reflect that it lives within that namespace.

app/patterns/

All test pattern source files should be stored in here.

app/templates/

All compiler template files should be stored in here.

The templates concerned with creating your application’s online documentation should be stored in the sub-directory app/templates/web.

The config/ directory typically contains the following files:

.
├── config/    
    ├── application.rb
    ├── boot.rb
    ├── commands.rb
    ├── maillist_dev.txt
    ├── maillist_prod.txt
    └── version.rb

Here is a description of each of them:

config/application.rb

Specifies global configuration for your application, for example to configure its source code repository, its web site url, or to setup the output directory and other attributes of Origen’s various generators.

This file is also defining an object that represents your application, this is automatically instantiated by Origen and is accessible via Origen.app. The application configuration is therefore accessible via Origen.app.config and also Origen.config for short. See the plugin guide for more information on accessing the application objects of plugins.

This application object is also commonly used to implement callback handlers and other globally accessible methods that are specific to your application.

config/boot.rb

This file is used by Origen to boot your application, i.e. it is the first thing that Origen will load whenever your application is invoked. By default, it simply requires the top-level lib file app/lib/<my_app_name>.rb and that is the file that you would normally modify to load additional application dependencies rather than the boot file.

In that case, what it the boot file for?

It fact, it is only relevant if your application is an Origen plugin and in that case there is a distinction between the application booting within its own workspace and when being boot as a dependency of another application. See the guide on Creating a Plugin for more information on this.

config/commands.rb

This file can be used to register and implement application-specific Origen commands to support your application.

See the dedicated guide on Adding Commands for more information.

config/maillist_dev.txt

This defines a list of email addresses that should be informed whenever there is any release of your application, including development releases.

See the guide on Users, Emails and Maillists for more information.

config/maillist_prod.txt

Similar to the development mailing list, this list of emails will only be notified whenever there is a production release of your application.

Note that there is no need to duplicate the development emails in this file, this is only the additional list of users that should be notified if the release is intended for production use.

config/version.rb

This file defines your application version, it is automatically updated by Origen whenever your application is released via the origen rc tag command.