rtapi.h
1 #ifndef RTAPI_H 2 #define RTAPI_H 3 4 /** RTAPI is a library providing a uniform API for several real time 5 operating systems. As of ver 2.0, RTLinux and RTAI are supported. 6 */ 7 /******************************************************************** 8 * Description: rtapi.h 9 * This file, 'rtapi.h', defines the RTAPI for both 10 * realtime and non-realtime code. 11 * 12 * Author: John Kasunich, Paul Corner 13 * License: LGPL Version 2.1 14 * 15 * Copyright (c) 2004 All rights reserved. 16 * 17 * Last change: 18 ********************************************************************/ 19 20 /** This file, 'rtapi.h', defines the RTAPI for both realtime and 21 non-realtime code. This is a change from Rev 2, where the non- 22 realtime (user space) API was defined in ulapi.h and used 23 different function names. The symbols RTAPI and ULAPI are used 24 to determine which mode is being compiled, RTAPI for realtime 25 and ULAPI for non-realtime. The API is implemented in files 26 named 'xxx_rtapi.c', where xxx is the RTOS. 27 */ 28 29 /** Copyright (C) 2003 John Kasunich 30 <jmkasunich AT users DOT sourceforge DOT net> 31 Copyright (C) 2003 Paul Corner 32 <paul_c AT users DOT sourceforge DOT net> 33 This library is based on version 1.0, which was released into 34 the public domain by its author, Fred Proctor. Thanks Fred! 35 */ 36 37 /** This library is free software; you can redistribute it and/or 38 modify it under the terms of version 2.1 of the GNU Lesser General 39 Public License as published by the Free Software Foundation. 40 This library is distributed in the hope that it will be useful, 41 but WITHOUT ANY WARRANTY; without even the implied warranty of 42 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 43 GNU Lesser General Public License for more details. 44 45 You should have received a copy of the GNU Lesser General Public 46 License along with this library; if not, write to the Free Software 47 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. 48 49 THE AUTHORS OF THIS LIBRARY ACCEPT ABSOLUTELY NO LIABILITY FOR 50 ANY HARM OR LOSS RESULTING FROM ITS USE. IT IS _EXTREMELY_ UNWISE 51 TO RELY ON SOFTWARE ALONE FOR SAFETY. Any machinery capable of 52 harming persons must have provisions for completely removing power 53 from all motors, etc, before persons enter any danger area. All 54 machinery must be designed to comply with local and national safety 55 codes, and the authors of this software can not, and do not, take 56 any responsibility for such compliance. 57 58 This code was written as part of the EMC HAL project. For more 59 information, go to www.linuxcnc.org. 60 */ 61 62 #if ( !defined RTAPI ) && ( !defined ULAPI ) 63 #error "Please define either RTAPI or ULAPI!" 64 #endif 65 #if ( defined RTAPI ) && ( defined ULAPI ) 66 #error "Can't define both RTAPI and ULAPI!" 67 #endif 68 69 #include <stddef.h> // provides NULL 70 71 72 #define RTAPI_NAME_LEN 31 /* length for module, etc, names */ 73 74 #ifdef __cplusplus 75 #define RTAPI_BEGIN_DECLS extern "C" { 76 #define RTAPI_END_DECLS } 77 #else 78 #define RTAPI_BEGIN_DECLS 79 #define RTAPI_END_DECLS 80 #endif 81 82 RTAPI_BEGIN_DECLS 83 84 /*********************************************************************** 85 * GENERAL PURPOSE FUNCTIONS * 86 ************************************************************************/ 87 88 /** 'rtapi_init() sets up the RTAPI. It must be called by any 89 module that intends to use the API, before any other RTAPI 90 calls. 91 'modname' can optionally point to a string that identifies 92 the module. The string will be truncated at RTAPI_NAME_LEN 93 characters. If 'modname' is NULL, the system will assign a 94 name. 95 On success, returns a positive integer module ID, which is 96 used for subsequent calls to rtapi_xxx_new, rtapi_xxx_delete, 97 and rtapi_exit. On failure, returns an error code as defined 98 above. Call only from within user or init/cleanup code, not 99 from realtime tasks. 100 */ 101 extern int rtapi_init(const char *modname); 102 103 /** 'rtapi_exit()' shuts down and cleans up the RTAPI. It must be 104 called prior to exit by any module that called rtapi_init. 105 'module_id' is the ID code returned when that module called 106 rtapi_init(). 107 Returns a status code. rtapi_exit() may attempt to clean up 108 any tasks, shared memory, and other resources allocated by the 109 module, but should not be relied on to replace proper cleanup 110 code within the module. Call only from within user or 111 init/cleanup code, not from realtime tasks. 112 */ 113 extern int rtapi_exit(int module_id); 114 115 /** 'rtapi_snprintf()' works like 'snprintf()' from the normal 116 C library, except that it may not handle long longs. 117 It is provided here because some RTOS kernels don't provide 118 a realtime safe version of the function, and those that do don't provide 119 support for printing doubles. On systems with a 120 good kernel snprintf(), or in user space, this function 121 simply calls the normal snprintf(). May be called from user, 122 init/cleanup, and realtime code. 123 */ 124 extern int rtapi_snprintf(char *buf, unsigned long int size, 125 const char *fmt, ...) 126 __attribute__((format(printf,3,4))); 127 128 /** 'rtapi_vsnprintf()' works like 'vsnprintf()' from the normal 129 C library, except that it doesn't handle long longs. 130 It is provided here because some RTOS kernels don't provide 131 a realtime safe version of the function, and those that do don't provide 132 support for printing doubles. On systems with a 133 good kernel vsnprintf(), or in user space, this function 134 simply calls the normal vsnrintf(). May be called from user, 135 init/cleanup, and realtime code. 136 */ 137 #include <stdarg.h> 138 extern int rtapi_vsnprintf(char *buf, unsigned long size, 139 const char *fmt, va_list ap); 140 141 /** 'rtapi_print()' prints a printf style message. Depending on the 142 RTOS and whether the program is being compiled for user space 143 or realtime, the message may be printed to stdout, stderr, or 144 to a kernel message log, etc. The calling syntax and format 145 string is similar to printf except that floating point and 146 longlongs are NOT supported in realtime and may not be supported 147 in user space. For some RTOS's, a 80 byte buffer is used, so the 148 format line and arguments should not produce a line more than 149 80 bytes long. (The buffer is protected against overflow.) 150 Does not block, but can take a fairly long time, depending on 151 the format string and OS. May be called from user, init/cleanup, 152 and realtime code. 153 */ 154 extern void rtapi_print(const char *fmt, ...) 155 __attribute__((format(printf,1,2))); 156 157 /** 'rtapi_print_msg()' prints a printf-style message when the level 158 is less than or equal to the current message level set by 159 rtapi_set_msg_level(). May be called from user, init/cleanup, 160 and realtime code. 161 */ 162 typedef enum { 163 RTAPI_MSG_NONE = 0, 164 RTAPI_MSG_ERR, 165 RTAPI_MSG_WARN, 166 RTAPI_MSG_INFO, 167 RTAPI_MSG_DBG, 168 RTAPI_MSG_ALL 169 } msg_level_t; 170 171 extern void rtapi_print_msg(msg_level_t level, const char *fmt, ...) 172 __attribute__((format(printf,2,3))); 173 174 175 /** Set the maximum level of message to print. In userspace code, 176 each component has its own independent message level. In realtime 177 code, all components share a single message level. Returns 0 for 178 success or -EINVAL if the level is out of range. */ 179 extern int rtapi_set_msg_level(int level); 180 /** Retrieve the message level set by the last call to rtapi_set_msg_level */ 181 extern int rtapi_get_msg_level(void); 182 183 /** 'rtapi_get_msg_handler' and 'rtapi_set_msg_handler' access the function 184 pointer used by rtapi_print and rtapi_print_msg. By default, messages 185 appear in the kernel log, but by replacing the handler a user of the rtapi 186 library can send the messages to another destination. Calling 187 rtapi_set_msg_handler with NULL restores the default handler. Call from 188 real-time init/cleanup code only. When called from rtapi_print(), 189 'level' is RTAPI_MSG_ALL, a level which should not normally be used 190 with rtapi_print_msg(). 191 */ 192 typedef void(*rtapi_msg_handler_t)(msg_level_t level, const char *fmt, va_list ap); 193 #ifdef RTAPI 194 extern void rtapi_set_msg_handler(rtapi_msg_handler_t handler); 195 extern rtapi_msg_handler_t rtapi_get_msg_handler(void); 196 #endif 197 198 /*********************************************************************** 199 * TIME RELATED FUNCTIONS * 200 ************************************************************************/ 201 202 /** NOTE: These timing related functions are only available in 203 realtime modules. User processes may not call them! 204 */ 205 #ifdef RTAPI 206 207 /** 'rtapi_clock_set_period() sets the basic time interval for realtime 208 tasks. All periodic tasks will run at an integer multiple of this 209 period. The first call to 'rtapi_clock_set_period() with 'nsecs' 210 greater than zero will start the clock, using 'nsecs' as the clock 211 period in nano-seconds. Due to hardware and RTOS limitations, the 212 actual period may not be exactly what was requested. On success, 213 the function will return the actual clock period if it is available, 214 otherwise it returns the requested period. If the requested period 215 is outside the limits imposed by the hardware or RTOS, it returns 216 -EINVAL and does not start the clock. Once the clock is started, 217 subsequent calls with non-zero 'nsecs' return -EINVAL and have 218 no effect. Calling 'rtapi_clock_set_period() with 'nsecs' set to 219 zero queries the clock, returning the current clock period, or zero 220 if the clock has not yet been started. Call only from within 221 init/cleanup code, not from realtime tasks. This function is not 222 available from user (non-realtime) code. 223 */ 224 extern long int rtapi_clock_set_period(long int nsecs); 225 #endif /* RTAPI */ 226 227 /** rtapi_delay() is a simple delay. It is intended only for short 228 delays, since it simply loops, wasting CPU cycles. 'nsec' is the 229 desired delay, in nano-seconds. 'rtapi_delay_max() returns the 230 max delay permitted (usually approximately 1/4 of the clock period). 231 Any call to 'rtapi_delay()' requesting a delay longer than the max 232 will delay for the max time only. 'rtapi_delay_max()' should be 233 called befure using 'rtapi_delay()' to make sure the required delays 234 can be achieved. The actual resolution of the delay may be as good 235 as one nano-second, or as bad as a several microseconds. May be 236 called from init/cleanup code, and from within realtime tasks. 237 */ 238 extern void rtapi_delay(long int nsec); 239 extern long int rtapi_delay_max(void); 240 241 242 /** rtapi_get_time returns the current time in nanoseconds. Depending 243 on the RTOS, this may be time since boot, or time since the clock 244 period was set, or some other time. Its absolute value means 245 nothing, but it is monotonically increasing and can be used to 246 schedule future events, or to time the duration of some activity. 247 Returns a 64 bit value. The resolution of the returned value may 248 be as good as one nano-second, or as poor as several microseconds. 249 May be called from init/cleanup code, and from within realtime tasks. 250 251 Experience has shown that the implementation of this function in 252 some RTOS/Kernel combinations is horrible. It can take up to 253 several microseconds, which is at least 100 times longer than it 254 should, and perhaps a thousand times longer. Use it only if you 255 MUST have results in seconds instead of clocks, and use it sparingly. 256 See rtapi_get_clocks() instead. 257 258 Note that longlong math may be poorly supported on some platforms, 259 especially in kernel space. Also note that rtapi_print() will NOT 260 print longlongs. Most time measurements are relative, and should 261 be done like this: deltat = (long int)(end_time - start_time); 262 where end_time and start_time are longlong values returned from 263 rtapi_get_time, and deltat is an ordinary long int (32 bits). 264 This will work for times up to about 2 seconds. 265 */ 266 extern long long int rtapi_get_time(void); 267 268 /** rtapi_get_clocks returns the current time in CPU clocks. It is 269 fast, since it just reads the TSC in the CPU instead of calling a 270 kernel or RTOS function. Of course, times measured in CPU clocks 271 are not as convenient, but for relative measurements this works 272 fine. Its absolute value means nothing, but it is monotonically 273 increasing* and can be used to schedule future events, or to time 274 the duration of some activity. (* on SMP machines, the two TSC's 275 may get out of sync, so if a task reads the TSC, gets swapped to 276 the other CPU, and reads again, the value may decrease. RTAPI 277 tries to force all RT tasks to run on one CPU.) 278 Returns a 64 bit value. The resolution of the returned value is 279 one CPU clock, which is usually a few nanoseconds to a fraction of 280 a nanosecond. 281 May be called from init/cleanup code, and from within realtime tasks. 282 283 Note that longlong math may be poorly supported on some platforms, 284 especially in kernel space. Also note that rtapi_print() will NOT 285 print longlongs. Most time measurements are relative, and should 286 be done like this: deltat = (long int)(end_time - start_time); 287 where end_time and start_time are longlong values returned from 288 rtapi_get_time, and deltat is an ordinary long int (32 bits). 289 This will work for times up to a second or so, depending on the 290 CPU clock frequency. It is best used for millisecond and 291 microsecond scale measurements though. 292 */ 293 extern long long int rtapi_get_clocks(void); 294 295 296 /*********************************************************************** 297 * TASK RELATED FUNCTIONS * 298 ************************************************************************/ 299 300 /** NOTE: These realtime task related functions are only available in 301 realtime modules. User processes may not call them! 302 */ 303 #ifdef RTAPI 304 305 /** NOTE: The RTAPI is designed to be a _simple_ API. As such, it uses 306 a very simple strategy to deal with SMP systems. It ignores them! 307 All tasks are scheduled on the first CPU. That doesn't mean that 308 additional CPUs are wasted, they will be used for non-realtime code. 309 */ 310 311 /** The 'rtapi_prio_xxxx()' functions provide a portable way to set 312 task priority. The mapping of actual priority to priority number 313 depends on the RTOS. Priorities range from 'rtapi_prio_lowest()' 314 to 'rtapi_prio_highest()', inclusive. To use this API, use one of 315 two methods: 316 317 1) Set your lowest priority task to 'rtapi_prio_lowest()', and for 318 each task of the next lowest priority, set their priorities to 319 'rtapi_prio_next_higher(previous)'. 320 321 2) Set your highest priority task to 'rtapi_prio_highest()', and 322 for each task of the next highest priority, set their priorities 323 to 'rtapi_prio_next_lower(previous)'. 324 325 A high priority task will preempt a lower priority task. The linux kernel 326 and userspace are always a lower priority than all rtapi tasks. 327 328 Call these functions only from within init/cleanup code, not from 329 realtime tasks. 330 */ 331 extern int rtapi_prio_highest(void); 332 extern int rtapi_prio_lowest(void); 333 extern int rtapi_prio_next_higher(int prio); 334 extern int rtapi_prio_next_lower(int prio); 335 336 /** 'rtapi_task_new()' creates but does not start a realtime task. 337 The task is created in the "paused" state. To start it, call 338 either rtapi_task_start() for periodic tasks, or rtapi_task_resume() 339 for free-running tasks. 340 On success, returns a positive integer task ID. This ID is used 341 for all subsequent calls that need to act on the task. On failure, 342 returns a negative error code as listed above. 'taskcode' is the 343 name of a function taking one int and returning void, which contains 344 the task code. 'arg' will be passed to 'taskcode' as an abitrary 345 void pointer when the task is started, and can be used to pass 346 any amount of data to the task (by pointing to a struct, or other 347 such tricks). 348 'prio' is the priority, as determined by one of the priority 349 functions above. 'owner' is the module ID of the module that 350 is making the call (see rtapi_init). 'stacksize' is the amount 351 of stack to be used for the task - be generous, hardware 352 interrupts may use the same stack. 'uses_fp' is a flag that 353 tells the OS whether the task uses floating point so it can 354 save the FPU registers on a task switch. Failing to save 355 registers when needed causes the dreaded "NAN bug", so most 356 tasks should set 'uses_fp' to RTAPI_USES_FP. If a task 357 definitely does not use floating point, setting 'uses_fp' to 358 RTAPI_NO_FP saves a few microseconds per task switch. Call 359 only from within init/cleanup code, not from realtime tasks. 360 */ 361 #define RTAPI_NO_FP 0 362 #define RTAPI_USES_FP 1 363 364 extern int rtapi_task_new(void (*taskcode) (void *), void *arg, 365 int prio, int owner, unsigned long int stacksize, int uses_fp); 366 367 /** 'rtapi_task_delete()' deletes a task. 'task_id' is a task ID 368 from a previous call to rtapi_task_new(). It frees memory 369 associated with 'task', and does any other cleanup needed. If 370 the task has been started, you should pause it before deleting 371 it. Returns a status code. Call only from within init/cleanup 372 code, not from realtime tasks. 373 */ 374 extern int rtapi_task_delete(int task_id); 375 376 /** 'rtapi_task_start()' starts a task in periodic mode. 'task_id' is 377 a task ID from a call to rtapi_task_new(). The task must be in 378 the "paused" state, or it will return -EINVAL. 379 'period_nsec' is the task period in nanoseconds, which will be 380 rounded to the nearest multiple of the global clock period. A 381 task period less than the clock period (including zero) will be 382 set equal to the clock period. 383 Call only from within init/cleanup code, not from realtime tasks. 384 */ 385 extern int rtapi_task_start(int task_id, unsigned long int period_nsec); 386 387 /** 'rtapi_wait()' suspends execution of the current task until the 388 next period. The task must be periodic, if not, the result is 389 undefined. The function will return at the beginning of the 390 next period. Call only from within a realtime task. 391 */ 392 extern void rtapi_wait(void); 393 394 /** 'rtapi_task_resume() starts a task in free-running mode. 'task_id' 395 is a task ID from a call to rtapi_task_new(). The task must be in 396 the "paused" state, or it will return -EINVAL. 397 A free running task runs continuously until either: 398 1) It is prempted by a higher priority task. It will resume as 399 soon as the higher priority task releases the CPU. 400 2) It calls a blocking function, like rtapi_sem_take(). It will 401 resume when the function unblocks. 402 3) it is returned to the "paused" state by rtapi_task_pause(). 403 May be called from init/cleanup code, and from within realtime tasks. 404 */ 405 extern int rtapi_task_resume(int task_id); 406 407 /** 'rtapi_task_pause() causes 'task_id' to stop execution and change 408 to the "paused" state. 'task_id' can be free-running or periodic. 409 Note that rtapi_task_pause() may called from any task, or from init 410 or cleanup code, not just from the task that is to be paused. 411 The task will resume execution when either rtapi_task_resume() or 412 rtapi_task_start() is called. May be called from init/cleanup code, 413 and from within realtime tasks. 414 */ 415 extern int rtapi_task_pause(int task_id); 416 417 /** 'rtapi_task_self()' returns the task ID of the current task or -EINVAL. 418 May be called from init/cleanup code, and from within realtime tasks. 419 */ 420 extern int rtapi_task_self(void); 421 422 #if defined(RTAPI_USPACE) || defined(USPACE) 423 424 #define RTAPI_TASK_PLL_SUPPORT 425 426 /** 'rtapi_task_pll_get_reference()' gets the reference timestamp 427 for the start of the current cycle. 428 Returns 0 if not called from within task context or on 429 platforms that do not support this. 430 */ 431 extern long long rtapi_task_pll_get_reference(void); 432 433 /** 'rtapi_task_pll_set_correction()' sets the correction value for 434 the next scheduling cycle of the current task. This could be 435 used to synchronize the task cycle to external sources. 436 Returns -EINVAL if not called from within task context or on 437 platforms that do not support this. 438 */ 439 extern int rtapi_task_pll_set_correction(long value); 440 #endif /* USPACE */ 441 442 #endif /* RTAPI */ 443 444 /*********************************************************************** 445 * SHARED MEMORY RELATED FUNCTIONS * 446 ************************************************************************/ 447 448 /** 'rtapi_shmem_new()' allocates a block of shared memory. 'key' 449 identifies the memory block, and must be non-zero. All modules 450 wishing to access the same memory must use the same key. 451 'module_id' is the ID of the module that is making the call (see 452 rtapi_init). The block will be at least 'size' bytes, and may 453 be rounded up. Allocating many small blocks may be very wasteful. 454 When a particular block is allocated for the first time, the first 455 4 bytes are zeroed. Subsequent allocations of the same block 456 by other modules or processes will not touch the contents of the 457 block. Applications can use those bytes to see if they need to 458 initialize the block, or if another module already did so. 459 On success, it returns a positive integer ID, which is used for 460 all subsequent calls dealing with the block. On failure it 461 returns a negative error code. Call only from within user or 462 init/cleanup code, not from realtime tasks. 463 */ 464 extern int rtapi_shmem_new(int key, int module_id, 465 unsigned long int size); 466 467 /** 'rtapi_shmem_delete()' frees the shared memory block associated 468 with 'shmem_id'. 'module_id' is the ID of the calling module. 469 Returns a status code. Call only from within user or init/cleanup 470 code, not from realtime tasks. 471 */ 472 extern int rtapi_shmem_delete(int shmem_id, int module_id); 473 474 /** 'rtapi_shmem_getptr()' sets '*ptr' to point to shared memory block 475 associated with 'shmem_id'. Returns a status code. May be called 476 from user code, init/cleanup code, or realtime tasks. 477 */ 478 extern int rtapi_shmem_getptr(int shmem_id, void **ptr); 479 480 /*********************************************************************** 481 * SEMAPHORE RELATED FUNCTIONS * 482 ************************************************************************/ 483 484 /** NOTE: These semaphore related functions are only available in 485 realtime modules. User processes may not call them! Consider 486 the mutex functions listed above instead. 487 */ 488 #ifdef RTAPI 489 490 /** 'rtapi_sem_new()' creates a realtime semaphore. 'key' identifies 491 identifies the semaphore, and must be non-zero. All modules wishing 492 to use the same semaphore must specify the same key. 'module_id' 493 is the ID of the module making the call (see rtapi_init). On 494 success, it returns a positive integer semaphore ID, which is used 495 for all subsequent calls dealing with the semaphore. On failure 496 it returns a negative error code. Call only from within init/cleanup 497 code, not from realtime tasks. 498 */ 499 extern int rtapi_sem_new(int key, int module_id); 500 501 /** 'rtapi_sem_delete()' is the counterpart to 'rtapi_sem_new()'. It 502 discards the semaphore associated with 'sem_id'. Any tasks blocked 503 on 'sem' will resume execution. 'module_id' is the ID of the calling 504 module. Returns a status code. Call only from within init/cleanup 505 code, not from realtime tasks. 506 */ 507 extern int rtapi_sem_delete(int sem_id, int module_id); 508 509 /** 'rtapi_sem_give()' unlocks a semaphore. If a higher priority task 510 is blocked on the semaphore, the calling task will block and the 511 higher priority task will begin to run. Returns a status code. 512 May be called from init/cleanup code, and from within realtime tasks. 513 */ 514 extern int rtapi_sem_give(int sem_id); 515 516 /** 'rtapi_sem_take()' locks a semaphore. Returns 0 or 517 -EINVAL. If the semaphore is unlocked it returns 0 518 immediately. If the semaphore is locked, the calling task blocks 519 until the semaphore is unlocked, then it returns 0. 520 Call only from within a realtime task. 521 */ 522 extern int rtapi_sem_take(int sem_id); 523 524 /** 'rtapi_sem_try()' does a non-blocking attempt to lock a semaphore. 525 Returns 0, -EINVAL, or -EBUSY. If the semaphore 526 is unlocked, it returns 0. If the semaphore is locked 527 it does not block, instead it returns -EBUSY, and the caller 528 can decide how to deal with the situation. Call only from within 529 a realtime task. 530 */ 531 extern int rtapi_sem_try(int sem_id); 532 533 #endif /* RTAPI */ 534 535 /*********************************************************************** 536 * FIFO RELATED FUNCTIONS * 537 ************************************************************************/ 538 539 /** 'rtapi_fifo_new()' creates a realtime fifo. 'key' identifies the 540 fifo, all modules wishing to access the same fifo must use the same 541 key. 'module_id' is the ID of the module making the call (see 542 rtapi_init). 'size' is the depth of the fifo. 'mode' is either 543 'R' or 'W', to request either read or write access to the fifo. 544 On success, it returns a positive integer ID, which is used for 545 subsequent calls dealing with the fifo. On failure, returns a 546 negative error code. Call only from within user or init/cleanup 547 code, not from realtime tasks. 548 */ 549 550 /* NOTE - RTAI fifos require (stacksize >= fifosze + 256) to avoid 551 oops messages on removal. 552 */ 553 extern int rtapi_fifo_new(int key, int module_id, 554 unsigned long int size, char mode); 555 556 /** 'rtapi_fifo_delete()' is the counterpart to 'rtapi_fifo_new()'. 557 It closes the fifo associated with 'fifo_ID'. 'module_id' is the 558 ID of the calling module. Returns status code. Call only from 559 within user or init/cleanup code, not from realtime tasks. 560 */ 561 extern int rtapi_fifo_delete(int fifo_id, int module_id); 562 563 /** FIFO notes. These comments apply to both read and write functions. 564 A fifo is a character device, an int is typically four bytes long... 565 If less than four bytes are sent to the fifo, expect corrupt data 566 out of the other end ! 567 The RTAI programming manual clearly states that the programmer is 568 responsible for the data format and integrity. 569 570 Additional NOTE: IMHO you should be able to write any amount of 571 data to a fifo, from 1 byte up to (and even beyond) the size of 572 the fifo. At a future date, the somewhat peculiar RTAI fifos 573 will be replaced with something that works better. John Kasunich 574 */ 575 576 /** NOTE: The fifo read and write functions operated differently in 577 realtime and user space. The realtime versions do not block, 578 but the userspace ones do. A future version of the RTAPI may 579 defined different names for the blocking and non-blocking 580 functions, but for now, just read the following docs carefully! 581 */ 582 583 #ifdef RTAPI 584 /** 'rtapi_fifo_read()' reads data from 'fifo_id'. 'buf' is a buffer 585 for the data, and 'size' is the maximum number of bytes to read. 586 Returns the number of bytes actually read, or -EINVAL. Does not 587 block. If 'size' bytes are not available, it will read whatever is 588 available, and return that count (which could be zero). Call only 589 from within a realtime task. 590 */ 591 #else /* ULAPI */ 592 /** 'rtapi_fifo_read()' reads data from 'fifo_id'. 'buf' is a buffer 593 for the data, and 'size' is the maximum number of bytes to read. 594 Returns the number of bytes actually read, or -EINVAL. If 595 there is no data in the fifo, it blocks until data appears (or 596 a signal occurs). If 'size' bytes are not available, it will 597 read whatever is available, and return that count (will be 598 greater than zero). If interrupted by a signal or some other 599 error occurs, will return -EINVAL. 600 */ 601 #endif /* ULAPI */ 602 603 extern int rtapi_fifo_read(int fifo_id, char *buf, 604 unsigned long int size); 605 606 #ifdef RTAPI 607 /** 'rtapi_fifo_write()' writes data to 'fifo_id'. Up to 'size' bytes 608 are taken from the buffer at 'buf'. Returns the number of bytes 609 actually written, or -EINVAL. Does not block. If 'size' bytes 610 of space are not available in the fifo, it will write as many bytes 611 as it can and return that count (which may be zero). 612 */ 613 #else /* ULAPI */ 614 /** 'rtapi_fifo_write()' writes data to 'fifo_id'. Up to 'size' bytes 615 are taken from the buffer at 'buf'. Returns the number of bytes 616 actually written, or -EINVAL. If 'size' bytes of space are 617 not available in the fifo, rtapi_fifo_write() may block, or it 618 may write as many bytes as it can and return that count (which 619 may be zero). 620 */ 621 #endif /* ULAPI */ 622 623 extern int rtapi_fifo_write(int fifo_id, char *buf, 624 unsigned long int size); 625 626 /*********************************************************************** 627 * INTERRUPT RELATED FUNCTIONS * 628 ************************************************************************/ 629 630 /** NOTE: These interrupt related functions are only available in 631 realtime modules. User processes may not call them! 632 */ 633 #ifdef RTAPI 634 635 /** 'rtapi_assign_interrupt_handler()' is used to set up a handler for 636 a hardware interrupt. 'irq' is the interrupt number, and 'handler' 637 is a pointer to a function taking no arguements and returning void. 638 'handler will be called when the interrupt occurs. 'owner' is the 639 ID of the calling module (see rtapi_init). Returns a status 640 code. Note: The simulated RTOS does not support interrupts. 641 Call only from within init/cleanup code, not from realtime tasks. 642 */ 643 extern int rtapi_irq_new(unsigned int irq_num, int owner, 644 void (*handler) (void)); 645 646 /** 'rtapi_free_interrupt_handler()' removes an interrupt handler that 647 was previously installed by rtapi_assign_interrupt_handler(). 'irq' 648 is the interrupt number. Removing a realtime module without freeing 649 any handlers it has installed will almost certainly crash the box. 650 Returns 0 or -EINVAL. Call only from within 651 init/cleanup code, not from realtime tasks. 652 */ 653 extern int rtapi_irq_delete(unsigned int irq_num); 654 655 /** 'rtapi_enable_interrupt()' and 'rtapi_disable_interrupt()' are 656 are used to enable and disable interrupts, presumably ones that 657 have handlers assigned to them. Returns a status code. May be 658 called from init/cleanup code, and from within realtime tasks. 659 660 */ 661 extern int rtapi_enable_interrupt(unsigned int irq); 662 extern int rtapi_disable_interrupt(unsigned int irq); 663 664 #endif /* RTAPI */ 665 666 /*********************************************************************** 667 * I/O RELATED FUNCTIONS * 668 ************************************************************************/ 669 670 /** 'rtapi_outb() writes 'byte' to 'port'. May be called from 671 init/cleanup code, and from within realtime tasks. 672 Note: This function does nothing on the simulated RTOS. 673 Note: Many platforms provide an inline outb() that is faster. 674 */ 675 extern void rtapi_outb(unsigned char byte, unsigned int port); 676 677 /** 'rtapi_inb() gets a byte from 'port'. Returns the byte. May 678 be called from init/cleanup code, and from within realtime tasks. 679 Note: This function always returns zero on the simulated RTOS. 680 Note: Many platforms provide an inline inb() that is faster. 681 */ 682 extern unsigned char rtapi_inb(unsigned int port); 683 684 #if defined(__KERNEL__) 685 /** 'rtapi_request_region() reserves I/O memory starting at 'base', 686 going for 'size' bytes, for component 'name'. 687 688 Note that on kernels before 2.4.0, this function always succeeds. 689 690 If the allocation fails, this function returns NULL. Otherwise, it returns 691 a non-NULL value. 692 */ 693 #include <linux/version.h> 694 #include <linux/ioport.h> 695 696 static __inline__ void *rtapi_request_region(unsigned long base, 697 unsigned long size, const char *name) { 698 return (void*)request_region(base, size, name); 699 } 700 701 /** 'rtapi_release_region() releases I/O memory reserved by 702 'rtapi_request_region', starting at 'base' and going for 'size' bytes. 703 'base' and 'size' must exactly match an earlier successful call to 704 rtapi_request_region or the result is undefined. 705 */ 706 static __inline__ void rtapi_release_region(unsigned long base, 707 unsigned long int size) { 708 release_region(base, size); 709 } 710 #else 711 #define rtapi_request_region(base, size, name) ((void*)-1) 712 #define rtapi_release_region(base, size) ((void)0) 713 #endif 714 715 /*********************************************************************** 716 * MODULE PARAMETER MACROS * 717 ************************************************************************/ 718 719 #ifdef RTAPI 720 721 /* The API for module parameters has changed as the kernel evolved, 722 and will probably change again. We define our own macro for 723 declaring parameters, so the code that uses RTAPI can ignore 724 the issue. 725 */ 726 727 /** RTAPI_MP_INT() declares a single integer module parameter. 728 RTAPI_MP_LONG() declares a single long module parameter. 729 RTAPI_MP_STRING() declares a single string module parameter. 730 RTAPI_MP_ARRAY_INT() declares an array of integer module parameters. 731 RTAPI_MP_ARRAY_LONG() declares an array of long module parameters. 732 RTAPI_MP_ARRAY_STRING() declares a single string module parameters. 733 'var' is the name of the variable used for the parameter, which 734 should be initialized with the default value(s) when it is declared. 735 'descr' is a short description of the parameter. 736 'num' is the number of elements in an array. 737 */ 738 739 #if !defined(__KERNEL__) 740 #define MODULE_INFO1(t, a, c) __attribute__((section(".modinfo"))) \ 741 t rtapi_info_##a = c; EXPORT_SYMBOL(rtapi_info_##a); 742 #define MODULE_INFO2x(t, a, b, c) MODULE_INFO2(t,a,b,c) 743 #define MODULE_INFO2(t, a, b, c) __attribute__((section(".modinfo"))) \ 744 t rtapi_info_##a##_##b = c; EXPORT_SYMBOL(rtapi_info_##a##_##b); 745 #define MODULE_PARM(v,t) MODULE_INFO2(const char*, type, v, t) MODULE_INFO2(void*, address, v, &v) 746 #define MODULE_PARM_DESC(v,t) MODULE_INFO2(const char*, description, v, t) 747 #define MODULE_LICENSE(s) MODULE_INFO1(const char*, license, s) 748 #define MODULE_AUTHOR(s) MODULE_INFO1(const char*, author, s) 749 #define MODULE_DESCRIPTION(s) MODULE_INFO1(const char*, description, s) 750 #define MODULE_SUPPORTED_DEVICE(s) MODULE_INFO1(const char*, supported_device, s) 751 #define MODULE_DEVICE_TABLE(x,y) MODULE_INFO2(struct rtapi_pci_device_id*, device_table, x, y) 752 #define MODULE_INFO(x,y) MODULE_INFO2x(char*, x, __LINE__, y) 753 #define EXPORT_SYMBOL(x) __attribute__((section(".rtapi_export"))) \ 754 char rtapi_exported_##x[] = #x; 755 #define EXPORT_SYMBOL_GPL(x) __attribute__((section(".rtapi_export"))) \ 756 char rtapi_exported_##x[] = #x; 757 #else 758 #ifndef LINUX_VERSION_CODE 759 #include <linux/version.h> 760 #endif 761 #endif 762 #ifndef KERNEL_VERSION 763 #define KERNEL_VERSION(a,b,c) (((a) << 16) + ((b) << 8) + (c)) 764 #endif 765 766 #ifndef LINUX_VERSION_CODE 767 #define LINUX_VERSION_CODE 0 768 #endif 769 770 #if !defined(__KERNEL__) 771 #define RTAPI_STRINGIFY(x) #x 772 773 774 #define RTAPI_MP_INT(var,descr) \ 775 MODULE_PARM(var,"i"); \ 776 MODULE_PARM_DESC(var,descr); 777 778 #define RTAPI_MP_LONG(var,descr) \ 779 MODULE_PARM(var,"l"); \ 780 MODULE_PARM_DESC(var,descr); 781 782 #define RTAPI_MP_STRING(var,descr) \ 783 MODULE_PARM(var,"s"); \ 784 MODULE_PARM_DESC(var,descr); 785 786 #define RTAPI_MP_ARRAY(type, var, num, descr) \ 787 MODULE_PARM(var,type); \ 788 MODULE_INFO2(int, size, var, num); \ 789 MODULE_PARM_DESC(var,descr); 790 791 #define RTAPI_MP_ARRAY_INT(var,num,descr) \ 792 RTAPI_MP_ARRAY("i", var, num, descr); 793 794 #define RTAPI_MP_ARRAY_LONG(var,num,descr) \ 795 RTAPI_MP_ARRAY("l", var, num, descr); 796 797 #define RTAPI_MP_ARRAY_STRING(var,num,descr) \ 798 RTAPI_MP_ARRAY("s", var, num, descr); 799 800 #else /* kernel */ 801 802 #include <linux/module.h> 803 804 #define RTAPI_MP_INT(var,descr) \ 805 module_param(var, int, 0); \ 806 MODULE_PARM_DESC(var,descr); 807 808 #define RTAPI_MP_LONG(var,descr) \ 809 module_param(var, long, 0); \ 810 MODULE_PARM_DESC(var,descr); 811 812 #define RTAPI_MP_STRING(var,descr) \ 813 module_param(var, charp, 0); \ 814 MODULE_PARM_DESC(var,descr); 815 816 #define RTAPI_MP_ARRAY_INT(var,num,descr) \ 817 int __dummy_##var; \ 818 module_param_array(var, int, &(__dummy_##var), 0); \ 819 MODULE_PARM_DESC(var,descr); 820 821 #define RTAPI_MP_ARRAY_LONG(var,num,descr) \ 822 int __dummy_##var; \ 823 module_param_array(var, long, &(__dummy_##var), 0); \ 824 MODULE_PARM_DESC(var,descr); 825 826 #define RTAPI_MP_ARRAY_STRING(var,num,descr) \ 827 int __dummy_##var; \ 828 module_param_array(var, charp, &(__dummy_##var), 0); \ 829 MODULE_PARM_DESC(var,descr); 830 831 #endif 832 833 #endif /* RTAPI */ 834 835 #if !defined(__KERNEL__) 836 extern long int simple_strtol(const char *nptr, char **endptr, int base); 837 838 #include <spawn.h> 839 840 int rtapi_spawn_as_root(pid_t *pid, const char *path, 841 const posix_spawn_file_actions_t *file_actions, 842 const posix_spawnattr_t *attrp, 843 char *const argv[], char *const envp[]); 844 845 int rtapi_spawnp_as_root(pid_t *pid, const char *path, 846 const posix_spawn_file_actions_t *file_actions, 847 const posix_spawnattr_t *attrp, 848 char *const argv[], char *const envp[]); 849 #endif 850 851 extern int rtapi_is_kernelspace(void); 852 extern int rtapi_is_realtime(void); 853 854 int rtapi_open_as_root(const char *filename, int mode); 855 856 RTAPI_END_DECLS 857 858 #endif /* RTAPI_H */