Chapter 6
Waveforms
This chapter discusses the construction and execution of Waveforms within REDHAWK. An Application is the software object that represents a Waveform, which is a collection of XML files describing the inter connection of and configuration of Components. It is possible to launch Waveforms in the Sandbox as well as in the REDHAWK Domain. This chapter discusses the mechanisms for launching a Waveform as a running Application in a Domain.
To complete the procedures in this chapter, the SigGen and HardLimit Components must be installed in $SDRROOT/dom/components.
6.1 Waveform Editor
The following sections further describe the definition of the Waveform as well as its creation and manipulation within the IDE. Like the PRF, SCD, and SPD XML files of a Component, a Waveform is completely represented by its Software Assembly Descriptor (SAD) file (*.sad.xml). The REDHAWK IDE provides a means of modifying the XML files without the need to directly edit this file by hand.
6.1.1 Overview Tab
Within the Overview tab, the name, Assembly Controller, and external Ports of a Waveform are defined.
The Assembly Controller is a Component instance in the Waveform that is designated as the Component where the Waveform-level start(), stop(), configure(), and query() calls are delegated. In complex Waveforms, the Assembly Controller can be used to orchestrate the life cycle of Components. In trivial Waveforms, the identity of the Assembly Controller is of less importance.
External Ports are used to make Component Ports available to other Applications, facilitating inter-Application connectivity.
Developers use the Overview tab to set the Assembly Controller for the Waveform and describe the Waveform.
The following steps explain how to set the Assembly Controller and describe the Waveform.
- On the Overview tab of the Waveform, from the Controller drop-down menu, ensure SigGen_1 is selected.
- In the Description field, enter a description for the Waveform.
6.1.2 Diagram Tab
Most of the work done on Waveforms takes place within the Diagram tab. The Diagram tab is very similar to the Sandbox/Chalkboard. Unlike the Sandbox, only Components that exist within the $SDRROOT can be added to the Waveform. The Palette contains a list of Components residing within the $SDRROOT. From the Diagram tab, external Ports of the Waveform can be indicated and the role of Assembly Controller can be assigned to a Component.
From the Diagram tab, Properties of Components can be set. When these Properties are set, they become specific to the Waveform and are written to the *.sad.xml file, which describes this Waveform.
6.1.2.1 Start Order
Each of the Components within the Waveform contain a number with a circle around it which represents that Component’s start order. The start order represents the order in which its start() method is called by the Assembly Controller. The only Component that does not have a start order is the Assembly Controller, which always has an assumed start order of 0. The Assembly Controller has a yellow circle containing 0. The start order may be changed by right-clicking a Component and selecting Move Start Order Earlier or Move Start Order Later from the context menu. The Assembly Controller may be changed by right-clicking a Component and selecting Set As Assembly Controller from the context menu.
6.1.3 SAD File Tab
The information put into the Overview and Diagram tabs is represented within the XML of the SAD file. The XML can be edited manually, but it is not recommended. Each of the Components used within the Waveform are referenced within the SAD file by pointing to the file location of the Component’s SPD file.
Instructions for inspecting the SAD file are below:
- Open the myWaveform.sad.xml tab of the Waveform Editor.
- Look through the SAD file and identify:
- The location of the two SPD files used in this Waveform (remember that this file location is in reference to the $SDRROOT)
- The Assembly Controller
- The connection between the two Components
- The external Port is set in the Diagram Tab
- The start order of each Component
- The Property is changed on the SigGen Component
- Before continuing, return to the Diagram tab and change the dataDouble_out Port so that it is no longer marked as an external Port.
6.2 Create and Deploy a Sample Waveform
This section describes the process of creating a Waveform, deploying this Waveform to the staging area, starting a Domain Manager and a Device Manager, creating an instance of an Application representing this Waveform, releasing the Application, and shutting down the Domain Manager and Device Manager.
The Domain Manager and Device Manager normally remain running during the creation/destruction of different Applications.
6.2.1 Create a Sample Waveform
Below is a description of how to create a Waveform:
- Select File > New > REDHAWK Waveform Project
- Set the Project name to demo
- Select Finish
This opens an editor on the demo.sad.xml file.
To add Components to this Waveform:
- Select the Diagram tab
- In the Palette, drag the SigGen Component onto the diagram
- In the Palette, drag the HardLimit Component onto the diagram
- Drag a connection between the SigGen_1 dataFloat_out Port and the HardLimit_1 dataFloat_in Port
- The Waveform looks like Figure 6.2:
- If SigGen_1 does not have a yellow 0, right-click the Component and select Set As Assembly Controller
- Press Ctrl+S to save or select File > Save
- Close the Waveform editor by selecting the X or by selecting File > Close All
6.2.2 Export the Waveform
Below is a description of how to export the Waveform in the IDE:
- In the Project Explorer View (typically on the left-side) select demo
- Drag the demo project onto the Target SDR in the REDHAWK Explorer View.
This installs the Waveform into $SDRROOT/dom/waveforms. If a permissions denied error is encountered, ensure that the $SDRROOT is set up per the installation instructions in Section D.1.2.
Verify that the Waveform is installed:
- In the REDHAWK Explorer View expand Target SDR.
- Expand Waveforms.
- Verify that the demo Waveform is shown.
6.2.3 Run the Waveform on the Runtime Environment
This section provides an overview of how to launch a Waveform as an Application and release an Application.
6.2.3.1 Launching a Domain
Begin by starting a Domain Manager and Device Manager (Section 11.1.1).
6.2.3.2 Launch the Waveform
- In the REDHAWK Explorer View right-click the REDHAWK_DEV Domain connection.
- Select Launch Waveform...
- Select the demo Waveform, then select Finish.
- To start the Waveform, select the Start Waveform (green triangle) button in the toolbar.
This opens the Waveform explorer. A Waveform is displayed in the REDHAWK Explorer by expanding the REDHAWK_DEV Domain connection and the Waveforms folder.
6.2.3.3 Open a Plot
- Left-click the dataFloat_out Port to select it.
- Right-click the Port to open the Port context menu.
- Select Plot Port Data. This opens a plot showing the plot data.
- To clearly view the sinusoid wave in the plot, reduce the frequency produced by SigGen.
- Open the Properties View and change the frequency Property to a value of 50.
6.2.3.4 Stop and Release the Application
- Select the Stop Waveform (red square) button in the toolbar. The plot stops updating.
- Select the Release Waveform (red X) button in the toolbar. The Waveform explorer closes.
6.2.3.5 Shutdown the Domain
Finally, shutdown the Domain Manager and Device Manager (Section 11.1.2).
6.3 Waveform Deployment and Computing Resources
Components are processes that run on a computer. As such, each Component takes up some arbitrary, often time-varying amount of spare capacity (for example, cpu computing load, memory, network I/O). REDHAWK manages computing resources on every computer under its Domain to minimize the likelihood that computing resources are over-subscribed. Each computer under REDHAWK’s Domain is managed through the GPP process.
6.3.1 GPP Device
The GPP Device is a specialized REDHAWK Device that manages the deployment of Components onto the computer and can be inspected like any other REDHAWK Device.
GPP can be in three possible usage states: IDLE, ACTIVE, or BUSY.
- IDLE indicates the GPP is not running any REDHAWK Components.
- ACTIVE indicates the GPP is running at least one Component, but has spare capacity to run additonal Components.
- BUSY indicates the GPP does not have any spare capacity to run additonal Components.
The usage state of any Device can be accessed through its usageState member. To inspect the usage state:
- In the IDE, select the “Advanced” tab of the “Properties” tab for the deployed Device.
- In a Python session, run the following script (assuming a Domain is running):
The GPP contains several Properties that are critical for the deployment of Components to a Device. When a Waveform is deployed, the framework scans through all IDLE and ACTIVE GPP Devices. The Component’s os and/or processor elements from its spd file are compared against the GPP’s os_name and/or processor_name Properties, respectively. If there is a match, the Component is assigned to that GPP. This search/assignment is performed for all Components in the Waveform. Once all Components have been assigned to specific GPPs, the deployment process begins.
6.3.1.1 Deployment Process
The deployment of a Component to a GPP begins by copying all relevant files from $SDRROOT/dom /components/<component>/ to the GPP’s cache. The GPP cache is a temporary directory on the computer used to run each Component (recall that REDHAWK is designed to support distributed processing). The cache is located in the local computer’s $SDRROOT/dev/.<Device Manager name>/<Device Name>. Note that the Component’s working directory is the GPP’s cache directory.
After all files are copied, the Component is started in its own process space using the fork system call. At program startup, the Component registers with the Domain Manager and the initial Property state is applied to the Component’s Property values. Next, connections are created as defined in the Waveform file. The Waveform is successfully deployed when all Waveform Components are registered with the Domain Manager and all Component initialization is complete.
6.3.1.2 Using Valgrind to Debug Components
The GPP supports launching Components using Valgrind, an open source tool that helps detect memory errors and leaks.
The VALGRIND environment variable controls this behavior:
- If VALGRIND is not set, Components launch as usual.
- If VALGRIND is set but has no value, the GPP searches the path for valgrind.
- If VALGRIND has a value, it is assumed to be the full path to the valgrind executable.
Valgrind log files are written to the same directory as the Component entry point within the GPP’s cache. For example, if the Component, MyComponent, has an entry point of cpp/MyComponent, the logs are written to MyComponent/cpp. The log file name follows the pattern valgrind.<PID>.log, where PID is the process ID of the Component.
6.3.2 Monitoring Computing Resources
The GPP monitors the following resources:
- System: cpu utilization, memory usage, NIC usage, total number of threads, and number of open files
- For each Component: cpu usage, memory usage, and process state
When a Component fails (for example, segfault), the GPP issues a
AbnormalComponentTerminationEventType message on the IDM_Channel. The message contains the Component id of the Component that failed, the Application id for the Component’s Waveform, and the Device id for the GPP that is running the Component.
The GPP contains a thresholds structure with five elements. The following table describes the elements of the thresholds structured Property:
|
The GPP contains a utilization structured Property that shows the overall system utilization at any time. The following table describes the elements of the utilization structured Property.
|
6.3.3 Capacity Reservation
A non-reservation strategy assumes that each process is running at full capacity at the time of execution. This is clearly not the case when the Waveform is initially deployed because all of the Waveform’s Components are in a stopped state, thus taking little to no system resources. Only after the Waveform is switched to a started state do the Components begin to consume system resources. Those system resources that are monitored for threshold changes by the GPP will directly affect the Device’s usageState: IDLE, ACTIVE, or BUSY.
A non-reservation strategy with a deployment pattern where multiple Waveforms are launched and not initially started but are delayed due to system events or predefined behavior, can create an over-utilized system. For example, a system may initially create twenty instances of a Waveform and later, start them as a result of an aperiodic event. All twenty Waveforms are created, but starting the 15th instance causes the CPU utilization for the entire system to reach 100%. When the next five Waveforms are started, the system will be over utilized, and all running Components will be affected leading to degraded system performance, such as data loss or lack of timely response to message events.
To mitigate this issue, the GPP maintains a reservation-based strategy to properly forecast the CPU load for each Component it manages. During initial Waveform deployment, the forecasted load for each Component of the Waveform is reserved against the current system’s available CPU capacity. As Components are moved to the start state, the forecasted load is tabled, and the actual load or a minimum utilitization load (whichever is greater), is used for determining the system load, and thus, the available CPU capacity. The available CPU capacity is one of the system resources that will directly determine the system’s usageState, (i.e., IDLE, ACTIVE, or BUSY ). The GPP’s utilization.subscribed Property maintains the runtime value of the total reservation for the system.
The Property, reserved_capacity_per_component, is the default forecasted load for every Component deployed by the GPP. A finer resolution forecast load can be provided when the Waveform is created. Currently, this is only available through the REDHAWK Python package when the Waveform is created. The following example describes how to set the reserved forcasted load for a Component. In this example, the Component, my_comp_1, on the Waveform, my_wave, has a reservation floor of 4 cpu cores.

REDHAWK Documentation is licensed under a Creative Commons Attribution-ShareAlike 3.0 Unported License.