Program Documentation
`
`Chimera 3.2
`The Real-Time Operating System
`for Reconfigurable Sensor-Based Control Systems
`
`February 8, 1995
`
`Darin Ingimarson
`David B. Stewart
`Pradeep K. Khosla
`
`The Robotics Institute • Dept. of Electrical and Computer Engineering
`Carnegie Mellon University
`
`

`

`Chimera 3.2
`Copyright © 1993, 1994, 1995 – all rights reserved.
`
`Chimera 3.2 was developed in the Advanced Manipulators Laboratory of the Robotics Institute, Carn-
`egie Mellon University (CMU).. The authors and CMU have used their best efforts in preparing the doc-
`umentation and the corresponding software. These efforts include development, research, and testing of
`the theories and programs to determine their effectiveness. See Section 0.1 (in Preface) for general
`terms, licensing, and limitation of liability.
`
`Advanced Manipulators Laboratory, The Robotics Institute
`and
`Department of Electrical and Computer Engineering
`
`Carnegie Mellon University
`5000 Forbes Avenue
`Pittsburgh, Pennsylvania 15213–3890
`
`Email address for bugs, fixes, questions, and comments: chimera@cmu.edu (internet)
`
`

`

`Chimera 3.2
`
`Table of Contents
`
`Preface.....................................................................................................................ix
`
`0.1 Licensing and other Terms........................................................................................ ix
`0.1.1 Chimera 3.2 General License Agreement............................................................. ix
`0.1.2
`Limitation of Liability ......................................................................................... xii
`0.1.3 BSD 4.3 Unix Terms............................................................................................ xii
`0.1.4 GNU General Public License............................................................................... xii
`0.1.5 GNU Library General Public License................................................................. xvi
`0.2 History of Chimera ................................................................................................ xxii
`0.3 Overview of Documentation................................................................................. xxiii
`0.4 List of New Features............................................................................................. xxiv
`0.4.1 Chimera 3.0 (released 1993) ............................................................................. xxiv
`0.4.2 Chimera 3.1 (November 1993) .......................................................................... xxv
`0.4.3 Chimera 3.2 (April 1994)................................................................................... xxv
`0.5 Acknowledgements............................................................................................... xxvi
`1. Beginner’s Tutorial .............................................................................................1
`
`

`

`iv
`
`Chimera 3.2 Table of Contents
`
`1.1 Setting up your Chimera 3.2 Environment .................................................................2
`1.2 A Simple Program Example .......................................................................................2
`1.3 A Multitasking Example.............................................................................................5
`1.4 A Real-Time Example ................................................................................................8
`1.5 Error Detection and Handling...................................................................................11
`1.6 Terminating a Chimera 3.2 Session ..........................................................................11
`1.7 Summary...................................................................................................................11
`2. User’s Manual....................................................................................................13
`
`2.1 Compiling and Linking Programs.............................................................................13
`2.1.1 C Code for RTPUs ............................................................................................... 14
`2.1.2 C++ Code for RTPUs........................................................................................... 15
`2.1.3 C Code for Host Workstation .............................................................................. 15
`2.1.4 Makefiles.............................................................................................................. 15
`2.2 chim Interface Commands ........................................................................................16
`2.2.1
`attach: Attach to an RTPU ................................................................................... 18
`2.2.2
`bg: Execute Program in Background ................................................................... 18
`2.2.3
`cd: Change Working Directory............................................................................ 18
`2.2.4
`detach: Detach from an RTPU............................................................................. 19
`2.2.5
`download: Download a File ................................................................................. 19
`2.2.6
`execute: Download and Execute Default RTPU.................................................. 19
`2.2.7
`fg: Continue Execution in Foreground ................................................................ 20
`2.2.8
`go: Execute Program............................................................................................ 20
`2.2.9
`kill: Interrupt Execution....................................................................................... 21
`2.2.10 killserver: Kill the qs Server ................................................................................ 21
`2.2.11 monitor: Use Monitor of Default RTPU.............................................................. 21
`2.2.12 pwd: Print Working Directory ............................................................................. 21
`2.2.13 quit: Quit from Console Process .......................................................................... 21
`2.2.14 rcd: Change Default Directory of RTPU ............................................................. 22
`2.2.15 select: Select the Default RTPU .......................................................................... 22
`2.2.16 status: Print Out Status of System........................................................................ 22
`2.2.17 tables: Start the tables Interface ........................................................................... 23
`2.2.18 version: Print Current Version Information......................................................... 24
`2.3 Ugraph.......................................................................................................................24
`2.3.1
`Starting ugraph..................................................................................................... 24
`2.3.2
`The Main Window ............................................................................................... 24
`2.3.3
`Plotting a Function............................................................................................... 25
`2.3.4
`Plotting UXDF Data ............................................................................................ 26
`2.3.5 Viewing the Raw Data ......................................................................................... 26
`2.3.6
`Legends and Labels.............................................................................................. 28
`2.3.7
`Line Types ........................................................................................................... 30
`2.3.8 Resizing the Graph............................................................................................... 30
`2.3.9 Ranges and Zooming ........................................................................................... 31
`2.3.10 Curve Interpolation Method................................................................................. 31
`2.3.11 Graph Sampling Period........................................................................................ 31
`2.3.12 Live Mode............................................................................................................ 32
`
`

`

`Chimera 3.2 Table of Contents
`
`v
`
`2.4 Debugging Chimera Programs..................................................................................33
`2.4.1
`Embedded I/O statements and macros................................................................. 33
`2.4.2
`The VMEbus Analyzer ........................................................................................ 34
`2.4.3
`Post-mortem debugging with the UNIX nm utility ............................................. 34
`2.4.4
`Post-mortem debugging with gidb....................................................................... 35
`2.5 Monitors....................................................................................................................43
`2.5.1
`Ironics IMON Monitor......................................................................................... 43
`2.5.2 Chimera IMONICA Monitor ............................................................................... 43
`2.6 tables Interface Commands.......................................................................................45
`2.6.1
`cpus: System CPU Tables.................................................................................... 45
`2.6.2
`devices: Device Driver Tables ............................................................................. 46
`2.6.3
`fds: File Descriptor Tables................................................................................... 46
`2.6.4
`host: Host Interface and Address Windows......................................................... 46
`2.6.5
`local: Host Mappings to VMEbus Devices.......................................................... 47
`2.6.6
`log: Log Configuration Information .................................................................... 48
`2.6.7 map: Mapping of VME Address Ranges to Host Windows ................................ 48
`2.6.8 memory: Memory Expansion Boards .................................................................. 48
`2.6.9
`options: Current Option Settings ......................................................................... 49
`2.6.10 quit: Quit from tables Interface............................................................................ 49
`2.6.11 resources: Resource Allocation............................................................................ 49
`2.6.12 xm: Express Mail Configuration.......................................................................... 49
`3. Programming Guidelines..................................................................................51
`
`3.1 File System Organization..........................................................................................52
`3.1.1
`Subdirectory Structure ......................................................................................... 52
`3.1.2
`Supporting Multiple Computing Architectures ................................................... 53
`3.1.3 Makefiles.............................................................................................................. 54
`3.2 Constants, Variables, and Subroutine Declarations..................................................56
`3.2.1 Register Variables................................................................................................ 56
`3.2.2 Variables .............................................................................................................. 57
`3.2.3 Global Variables .................................................................................................. 58
`3.2.4
`Subroutines .......................................................................................................... 60
`3.3 Naming Conventions ................................................................................................60
`3.3.1 Macros and Constants .......................................................................................... 61
`3.3.2
`Local Variables and Subroutines ......................................................................... 61
`3.3.3
`Types.................................................................................................................... 62
`3.3.4 Global State Variables ......................................................................................... 62
`3.4 Libraries ....................................................................................................................63
`3.4.1
`Subroutine Libraries............................................................................................. 64
`3.4.2 Device Driver Libraries ....................................................................................... 64
`3.4.3 Reconfigurable Module Libraries ........................................................................ 64
`3.5 General Coding Tips .................................................................................................65
`3.5.1
`Loops.................................................................................................................... 65
`3.5.2
`State Variable Table............................................................................................. 65
`3.5.3 Generating the Framework for a Reconfigurable Module................................... 66
`3.5.4
`Special Purpose Processors.................................................................................. 66
`
`

`

`vi
`
`Chimera 3.2 Table of Contents
`
`3.6 Device Drivers ..........................................................................................................66
`3.6.1
`I/O Device (IOD) Drivers .................................................................................... 67
`3.6.2
`Sensor-Actuator Interface (Second-Level Driver)............................................... 68
`3.6.3
`Special Purpose Processor Drivers ...................................................................... 69
`3.7 Documentation..........................................................................................................69
`3.7.1 Documenting a Reconfigurable Module.............................................................. 69
`3.8 Peer Review of Code ................................................................................................70
`3.9 Sample Documentation of a Reconfigurable Module...............................................71
`4. Programmer’s Manual......................................................................................75
`
`4.1 Standard Types, Constants, and Macros ...................................................................76
`4.1.1 ASCII Character Set ............................................................................................ 76
`4.1.2 Chimera 3.2 Constants ......................................................................................... 76
`4.1.3
`Standard Library Constants.................................................................................. 78
`4.1.4 Weights and Measures ......................................................................................... 79
`4.1.5 Basic Types.......................................................................................................... 84
`4.1.6 Variable Types ..................................................................................................... 85
`4.1.7 Debugging Utility Macros ................................................................................... 87
`4.2 Chimera Libraries .....................................................................................................88
`4.2.1 Concurrent Standard Input/Output (stdio) Library .............................................. 88
`4.2.2
`Standard Directory Operations Library ............................................................... 94
`4.2.3 Chimera Directory Operations............................................................................. 96
`4.2.4
`String Library....................................................................................................... 97
`4.2.5
`Type Conversion:............................................................................................... 100
`4.2.6 Memory Operations: .......................................................................................... 101
`4.2.7 Bit Field Operations:.......................................................................................... 103
`4.2.8 Random Number Routines................................................................................. 105
`4.2.9
`Sorting and Searching Routines......................................................................... 107
`4.2.10 User Interface Packet Utility.............................................................................. 107
`4.2.11 Command Interpreter:........................................................................................ 112
`4.2.12 Configuration File Reading Utility .................................................................... 120
`4.2.13 Configuration and Data File “define” Mechanism ............................................ 130
`4.2.14 Math Functions .................................................................................................. 131
`4.2.15 Matrix Math Libraries........................................................................................ 134
`4.2.16 Memory Allocation Routines:............................................................................ 143
`4.2.17 Time-of-Day Library ......................................................................................... 145
`4.2.18 Universal Experimental Data Format (UXDF) Library..................................... 147
`4.3 Task Control Primitives ..........................................................................................151
`4.3.1 Creating a Task .................................................................................................. 151
`4.3.2
`Terminating a Task ............................................................................................ 153
`4.3.3
`Physical Time..................................................................................................... 153
`4.3.4
`Task Timing Primitives...................................................................................... 154
`4.3.5
`Task Priorities .................................................................................................... 157
`4.4 Local Communication and Synchronization...........................................................158
`4.4.1 RTPU Local Shared Memory ............................................................................ 158
`4.4.2 RTPU Local Semaphores................................................................................... 159
`4.4.3 Host Workstation Local Shared Memory .......................................................... 160
`
`

`

`Chimera 3.2 Table of Contents
`
`vii
`
`4.4.4 Host Workstation Local Semaphores................................................................. 162
`4.5 Interprocessor Communication and Synchronization.............................................163
`4.5.1
`Interprocessor Shared Memory.......................................................................... 164
`4.5.2 Remote Semaphores........................................................................................... 167
`4.5.3
`Interprocessor Message Passing ........................................................................ 169
`4.5.4 One-to-One Triple-Buffer Communication ....................................................... 172
`4.5.5 Global State Variable Table Mechanism ........................................................... 175
`4.5.6
`Extended File System ........................................................................................ 187
`4.5.7
`Ethernet Interface Passing.................................................................................. 189
`4.6 Host Procedure Calls...............................................................................................193
`4.7 Host Interface to Chimera Utilities .........................................................................194
`4.8 Generic Interfaces ...................................................................................................196
`4.8.1 Reconfigurable I/O Device Drivers ................................................................... 196
`4.8.2
`Sensor/Actuator Independent Interface.............................................................. 202
`4.8.3
`Special Purpose Processors................................................................................ 206
`4.9 Command Line Arguments.....................................................................................217
`4.10 Error and Exception Handling ................................................................................218
`4.10.1 Deadline Failure Detection and Handling.......................................................... 218
`4.10.2 Global Error Handling ....................................................................................... 220
`4.10.3 UNIX-compatible Error Handling ..................................................................... 233
`4.11 Kernel Level Routines ............................................................................................233
`4.11.1 Kernel-Level Task Synchronization .................................................................. 234
`4.11.2 Setjmp and Longjmp: Global Goto Statements ................................................. 235
`4.11.3 Forcing a Reschedule......................................................................................... 236
`4.11.4 System Conversion Utilities .............................................................................. 236
`4.11.5 Changing the Vector Base Register ................................................................... 237
`4.11.6 Accessing CPU Registers .................................................................................. 238
`4.11.7 Setting CPU Priority Level ................................................................................ 239
`4.11.8 C Access to User Traps...................................................................................... 240
`4.11.9 Testing Existence of Memory............................................................................ 241
`4.11.10 Low-level Multiprocessor Synchronization Primitives ..................................... 241
`4.11.11 Polling Mechanisms........................................................................................... 242
`4.12 The Chimera Default Scheduler..............................................................................244
`4.12.1 Real-time clock resolution ................................................................................. 244
`4.12.2 Time Overflow................................................................................................... 245
`4.13 Reconfigurable Subsystems ....................................................................................245
`4.13.1 Reconfigurable Module Interface Specification ................................................ 246
`4.13.2 Subsystem (SBS) Interface ................................................................................ 252
`4.13.3 SBS Interactive Command Interpreter............................................................... 261
`4.13.4 Subsystem Specification File (.sbs file)............................................................. 266
`4.13.5 Reconfigurable Module Specification (.rmod) file............................................ 269
`4.13.6 Network Commands .......................................................................................... 271
`4.13.7 Network Packet Specifications .......................................................................... 278
`4.13.8 Parallel Subsystems ........................................................................................... 285
`5. System’s Manual .............................................................................................287
`
`

`

`viii
`
`Chimera 3.2 Table of Contents
`
`5.1 System Details under Normal Operation ................................................................287
`5.1.1
`Starting Up Chimera 3.2 .................................................................................... 287
`5.1.2 Downloading Programs ..................................................................................... 288
`5.1.3
`Executing Programs ........................................................................................... 290
`5.2 Writing Device Drivers...........................................................................................292
`5.2.1
`I/O Device (IOD) Drivers .................................................................................. 292
`5.2.2
`Sensor/Actuator Interface (SAI) Drivers ........................................................... 302
`5.2.3
`Special Purpose Processor (SPP) Drivers .......................................................... 305
`5.2.4
`Installing IOD, SAI, and SPP Drivers ............................................................... 305
`5.3 Interrupt and Exception Handlers ...........................................................................305
`5.3.1
`Local Interrupts.................................................................................................. 306
`5.3.2 VMEbus Interrupts............................................................................................. 307
`5.3.3 Mailbox Interrupts ............................................................................................. 307
`5.3.4
`Exception Handlers............................................................................................ 308
`5.4 Customizing a Kernel .............................................................................................309
`6. Installation Manual .........................................................................................311
`
`6.1 Supported Hardware ...............................................................................................312
`6.1.1 Host Workstation Hardware .............................................................................. 312
`6.1.2 RTPU Hardware................................................................................................. 313
`6.1.3
`I/O Device Hardware ......................................................................................... 313
`6.2 Hardware Addressing..............................................................................................313
`6.3 Hardware Installation..............................................................................................315
`6.3.1 RTPU Hardware Installation.............................................................................. 316
`6.3.2 Adaptor Hardware Installation........................................................................... 325
`6.3.3
`Special Purpose Processor Installation .............................................................. 332
`6.4 Software Installation ...............................................................................................333
`6.4.1
`Setting Up the Chimera Environment................................................................ 333
`6.4.2
`Loading the Software......................................................................................... 334
`6.4.3 Building a New SunOS 4.x.x Kernel ................................................................. 334
`6.4.4
`Sun3 and Sun4 Installation ................................................................................ 335
`6.4.5
`Sun4c (Sun SPARCstation) Installation ............................................................ 339
`6.5 Creating a Configuration File .................................................................................341
`6.5.1
` Sample Configuration Files .............................................................................. 341
`6.5.2 Options: ‘‘o’’ Entries ......................................................................................... 344
`6.5.3 Host Workstation Information: “h” Entries ....................................................... 344
`6.5.4 RTPUs: ‘‘r’’ Entries........................................................................................... 348
`6.5.5
`Special Purpose Processors: “s” Entries ............................................................ 349
`6.5.6 Memory Expansion Boards: “m” and “n” Entries ............................................. 349
`6.5.7
`I/O Devices (new Chimera 3.0 format): “i” Entry............................................. 350
`6.5.8
`I/O Devices (old Chimera II format): ‘‘d’’ Entry .............................................. 351
`6.6 Troubleshooting Your Installation..........................................................................352
`Index .....................................................................................................................355
`
`

`

`Chimera 3.2
`
`Preface
`
`0.1 Licensing and other Terms
`
`The rights to Chimera 3.2 belong to Carnegie Mellon University (CMU), as it was originally developed as
`a research project. Chimera 3.2 is distributed with the terms outlined below.
`
`Every attempt is made to keep the manuals up to date. However, as in any large software product, their is a
`tendency for the version of the manual to not coincide with the software version. In some cases, the
`document actually outdates the software, because the documentation was often used as an informal
`specification of the product. The version number on the cover of this manual should be up to date with
`software of the same version number. Any differences should be reported to <chimera@cmu.edu>.
`
`0.1.1 Chimera 3.2 General License Agreement
`
`Licensing Agreement for Academic, Educational, and Research Purposes
`
`We provide Chimera 3.2 and associated software products together with this license agreement. We grant
`you a license to use the software product in machine-readable form for research, educational, and academic
`purposes only, provided that any software modules developed for Chimera are made freely available for use
`by other licensed Chimera users.
`
`

`

`x
`
`Chimera 3.2
`
`1. Carnegie Mellon University (CMU) has certain rights to the computer software,
`electronic information and data, in all forms and versions, identified as Chimera,
`described
`in CMU Docket 95-035,
`including associated documentation
`(“Program”).
`
`2. CMU grants to LICENSEE a fully-paid, nonexclusive, and nontransferable license
`to use the Program furnished hereunder, upon the terms and conditions set out
`below.
`
`3. LICENSEE acknowledges that the Program is a research tool still in the
`development stage, that it is being supplied “as is,” without any accompanying
`services or improvements from CMU, and that this license is entered into in order
`to encourage scientific collaboration aimed at further development and application
`of the Program.
`
`4. CMU MAKES NO WARRANTIES OF ANY KIND, EITHER EXPRESSED OR
`IMPLIED AS TO ANY MATTER INCLUDING, BUT NOT LIMITED TO,
`WARRANTY OF FITNESS FOR PURPOSE, OR MERCHANTABILITY,
`EXCLUSIVITY OR RESULTS OBTAINED FROM SPONSOR’S USE OF ANY
`INTELLECTUAL PROPERTY DEVELOPED UNDER THIS AGREEMENT,
`NOR SHALL EITHER PARTY HERETO BE LIABLE TO THE OTHER FOR
`INDIRECT, SPECIAL, OR CONSEQUENTIAL DAMAGES SUCH AS LOSS
`OF PROFITS OR INABILITY TO USE SAID INTELLECTUAL PROPERTY
`OR ANY APPLICATIONS AND DERIVATION THEREOF. CMU DOES NOT
`MAKE ANY WARRANTY OF ANY KIND WITH RESPECT TO FREEDOM
`FROM PATENT, TRADEMARK, OR COPYRIGHT INFRINGEMENT, OR
`THEFT OF TRADE SECRETS AND DOES NOT ASSUME ANY LIABILITY
`HEREUNDER FOR ANY
`INFRINGEMENT OF ANY PATENT,
`TRADEMARK, OR COPYRIGHT ARISING FROM THE USE OF THE
`PROGRAM, INFORMATION, INTELLECTUAL PROPERTY, OR OTHER
`PROPERTY OR RIGHTS GRANTED OR PROVIDED TO IT HEREUNDER.
`THE USER AGREES THAT IT WILL NOT MAKE ANY WARRANTY ON
`BEHALF OF CMU, EXPRESSED OR IMPLIED, TO ANY PERSON
`CONCERNING THE APPLICATION OF OR THE RESULTS TO BE
`OBTAINED WITH THE PROGRAM UNDER THIS AGREEMENT.
`
`LICENSEE agrees that it will not make any warranty on behalf of CMU, express
`or implied, to any person concerning the application of or the results to be obtained
`with the Program.
`
`5. LICENSEE agrees that it will use the Program solely for research, educational, and
`academic purposes only, and shall not distribute or transfer it to another location
`or to any other person without prior written permission from CMU. This Program,
`or any portion thereof, may not be used for commercial purpos