README
1 README for RTAPI 2 3 RTAPI is a wrapper API that allows realtime programs to use either 4 RTLinux or RTAI with no code changes. 5 6 Files: 7 8 Makefile : the Makefile 9 README : this file 10 rtapi.h : decls for the generic RTAPI functions. 11 rtapi_app.h : decls for the kernel modules 12 rtapi_common.h : Collection of typedefs, etc, used internally by RTAPI. 13 procfs_macros.h : Macros used to impliment the /proc interface 14 rtapi_proc.h : more stuff implementing the /proc interface 15 rtai_rtapi.c : implementation of real-time API, for RTAI 16 rtai_ulapi.c : implementation of user-level API, for RTAI 17 uspace_rtapi.c : implementation of real-time API, for POSIX RTOS 18 uspace_ulapi.c : implementation of user-level API, for POSIX RTOS 19 20 21 ../../Makefile.inc : contains compile-time flags, etc. 22 ../../configure : script that creates Makefile.inc 23 24 The Build Process 25 ----------------- 26 The build process follows the standard Linux convention: 27 28 ./configure 29 make 30 31 The configure script and make are intended to be run from the 32 root of the emc2 tree, to make the entire emc2 project. See the 33 README in that directory for more details. 34 35 To run the examples: 36 37 1. Open a shell window, and begin watching the kernel log: 38 39 tail -f /var/log/messages 40 41 leave this running, and go back to your original shell window 42 you should be in the emc2 directory 43 44 2. Load the RTOS and RTAPI modules: 45 46 Note: for this and most of the following steps you will need 47 to be root, or use 'su -c "<command>"' 48 49 scripts/load_rtapi 50 51 See a number of messages pop up in the kernel log as components 52 of the RTOS are installed... 53 One of the last ones will be: 54 55 <date> <time> <host> kernel: RTAPI: Init complete 56 57 This means that the rtapi module (rtai_rtapi.o) is loaded. 58 59 3. Run the timer task example: 60 61 /sbin/insmod rtlib/timertask.o 62 63 A few messages will pop up in the kernel log as the task 64 is created and started: 65 66 <date> <time> <host> kernel: timertask init: desired clock 10000000, actual 10000168 67 <date> <time> <host> kernel: timertask init: started timer task 68 <date> <time> <host> kernel: timertask init: max delay = 2500042 69 70 Wait a few seconds, then remove the module: 71 72 /sbin/rmmod timertask 73 74 A couple more messages from timertask: 75 76 <date> <time> <host> kernel: timertask exit: timer count is 8174 77 78 This means that 8174 calls to the task were made. (I let it 79 run for about 8 seconds.) 80 81 4. Run the parallel port interrupt example: 82 83 /sbin/insmod rtlib/extint.o 84 85 Short pin 10 to pin 25 on the parallel port a couple of times to 86 generate some interrupts, then view the count in the kernel log: 87 88 /sbin/rmmod extint 89 90 Again, you'll get messages from the extint module: 91 92 <date> <time> <host> kernel: extint: interrupt count is 2522 93 94 This means 2,522 interrupts occurred, many for a single short 95 of pin 10 due to contact noise. 96 97 5. Run the shared memory example: 98 99 /sbin/insmod rtlib/shmemtask.o 100 101 bin/shmemusr 102 103 See the shared memory heartbeat incrementing. 104 Use crtl-C to break out of shmemusr. 105 Then remove the realtime task 106 107 /sbin/rmmod shmemtask 108 109 6. Run the semaphore example: 110 111 /sbin/insmod rtlib/master.o 112 113 The master task will start giving the semaphore once per 114 second, printing to the log when it does. 115 116 /sbin/insmod rtlib/slave.o 117 118 The slave attempts to get the semaphore, and prints each 119 time it succeeds. Since the master has already given the 120 semaphore several times, and it is a counting semaphore, 121 the slave will run several times in a row. Once it catches 122 up with the master, it will run right after the master runs. 123 Stop the tasks in reverse order: 124 125 /sbin/rmmod slave 126 /sbin/rmmod master 127 128 7. Run the FIFO example: 129 130 /sbin/insmod rtlib/fifotask.o 131 132 The realtime fifotask will begin writing strings to the 133 fifo once per second, and echoing the strings to the log 134 file. 135 136 bin/fifousr 137 138 The user mode program will read strings from the fifo and 139 and print them out. 140 141 Use ctrl-c to exit fifousr, and stop the task: 142 143 /sbin/rmmod fifotask 144 145 146 8. More elaborate tests: 147 148 In theory, you should be able to run any or all of the 149 above tests at the same time, doing insmod's and rmmod's 150 in any order. 151 152 9. Shutting down. 153 154 To remove the rtapi and the rest of the RTOS modules: 155 156 scripts/unload_rtapi 157 158 If any tasks are still running, the script should print 159 the module names and refuse to proceed. Shut down the 160 modules (rmmod) and try again. 161 162 The /proc/rtapi Interface 163 ------------------------- 164 165 Various files in /proc/rtapi provide information on the internal status 166 of RTAPI. In order, these are: 167 168 debug : Shows which message types will be printed to /var/log/messages. 169 This can be altered by writing a digit to debug. See rtapi.h 170 for the relevant values. 171 172 fifos : Lists the fifos currently in use, and by which process ID. 173 174 modules : Lists the loaded module names, IDs, and the type 175 (realtime or user space). 176 177 sems : Lists the semaphores currently in use. 178 179 shmem : Lists the shared memory allocated and the size. 180 181 status : Provides information about the number of tasks, and timer status. 182 183 tasks : Lists task ID, priority, etc. 184 185 For a quick look at the status of the rtapi, do "cat /proc/rtapi/*" 186 187 The Uninstall Process 188 --------------------- 189 190 make clean 191 192 Code Layout 193 ----------- 194 195 The code is split among src/ and example/ directories, each with its 196 own Makefile. There is also a top-level Makefile and a Makefile.inc 197 that is included by each of the src/ Makefiles. The 'configure' script 198 creates Makefile.inc based on some heuristics that determine whether 199 you have RTL or RTAI, and defines compiler flags accordingly. The 200 config script is a shell script (/bin/sh), which gives great 201 flexibility in what can be done. 'config' currently checks to see what 202 real-time Linux installations exist, using 'find' and checking for 203 "rtl.mk" and ".buildvars" as the telltale signs. If found, RTDIR is set 204 to the associated parent directory. 205 Alternatively, RTDIR can be set via a command line argument as described 206 in "The Build Process". This gives us the flexibility to cross-compile on 207 a system not running a realtime kernel. 208 209 If an installation is found, then symbols for the RT Linux type, 210 compile flags, etc. are included in the Makefile.inc. If an invalid 211 directory is specified, or the correct marker file is not found, configure 212 will exit with a "Usage" message. 213 214 215 Makefiles 216 --------- 217 The general form for a makefile entry is: 218 219 target : dependencies 220 rules 221 222 where <target> is what you want made, <dependencies> are the things 223 the target depends on, and <rules> are how to build the target from the 224 dependencies. Lines can be continued with the \ backslash character at 225 the end of the line to be continued. Each line of the rules must begin 226 with a TAB character. In general a makefile entry looks more like 227 this: 228 229 target : dependency_1 dependency_2 \ 230 ... \ 231 dependency_n 232 [TAB] rule_1 233 [TAB] long rule \ 234 rest of long rule 235 [TAB] ... 236 [TAB] rule_n 237 238 You can only have one target per entry, but as many dependencies and 239 rules as you need. You can also have multiple different entries for 240 the same target; you can see this at the end of the Makefiles with the 241 header file dependencies generated by 'makedepend', after the "DO NOT 242 REMOVE THIS LINE" line. 243 244 In order to minimize the number of files, each src/ Makefile compiles 245 directly into the lib/ or bin/ directories. Thus, the targets and 246 rules aren't as simple as this: 247 248 foo.o : foo.c 249 gcc -c foo.c -o foo.o 250 251 but look like this: 252 253 LIB_DIR = ../../lib 254 255 $(LIB_DIR)/foo.o : foo.c 256 gcc -c foo.c -o $(LIB_DIR)/foo.o 257 258 This means that the resulting .o file doesn't lie around in the 259 current directory, but is generated directly in the ../../lib 260 directory. 261 262 The actual rules are a little more complicated since we like to use 263 make's shorthand variables. These are: 264 265 $@ for the target 266 $< for the first dependency 267 $^ for all the dependencies 268 269 The preceding example would then be 270 271 LIB_DIR = ../../lib 272 273 $(LIB_DIR)/foo.o : foo.c 274 gcc -c $< -o $@ 275 276 277 Configuration Notes 278 ------------------- 279 chmod a+rw /dev/rtai_shm, for RTAI 280 chmod a+rw /dev/mem, for mbuff 281