[ae68ff0] | 1 | @c |
---|
[1b03eed] | 2 | @c COPYRIGHT (c) 1988-2007. |
---|
[ae68ff0] | 3 | @c On-Line Applications Research Corporation (OAR). |
---|
| 4 | @c All rights reserved. |
---|
| 5 | @c |
---|
[139b2e4a] | 6 | @c $Id$ |
---|
| 7 | @c |
---|
[ae68ff0] | 8 | |
---|
| 9 | @chapter I/O Manager |
---|
[20515fc] | 10 | |
---|
[169502e] | 11 | @cindex device drivers |
---|
| 12 | @cindex IO Manager |
---|
| 13 | |
---|
[ae68ff0] | 14 | @section Introduction |
---|
| 15 | |
---|
| 16 | The input/output interface manager provides a |
---|
| 17 | well-defined mechanism for accessing device drivers and a |
---|
| 18 | structured methodology for organizing device drivers. The |
---|
| 19 | directives provided by the I/O manager are: |
---|
| 20 | |
---|
| 21 | @itemize @bullet |
---|
[f331481c] | 22 | @item @code{@value{DIRPREFIX}io_initialize} - Initialize a device driver |
---|
[e70f201] | 23 | @item @code{@value{DIRPREFIX}io_register_driver} - Register a device driver |
---|
[f331481c] | 24 | @item @code{@value{DIRPREFIX}io_register_name} - Register a device name |
---|
| 25 | @item @code{@value{DIRPREFIX}io_lookup_name} - Look up a device name |
---|
| 26 | @item @code{@value{DIRPREFIX}io_open} - Open a device |
---|
| 27 | @item @code{@value{DIRPREFIX}io_close} - Close a device |
---|
| 28 | @item @code{@value{DIRPREFIX}io_read} - Read from a device |
---|
| 29 | @item @code{@value{DIRPREFIX}io_write} - Write to a device |
---|
| 30 | @item @code{@value{DIRPREFIX}io_control} - Special device services |
---|
[ae68ff0] | 31 | @end itemize |
---|
| 32 | |
---|
| 33 | @section Background |
---|
[20515fc] | 34 | |
---|
[ae68ff0] | 35 | @subsection Device Driver Table |
---|
| 36 | |
---|
[169502e] | 37 | @cindex Device Driver Table |
---|
| 38 | |
---|
[6d00095] | 39 | Each application utilizing the RTEMS I/O manager must specify the |
---|
| 40 | address of a Device Driver Table in its Configuration Table. This table |
---|
| 41 | contains each device driver's entry points that is to be initialised by |
---|
| 42 | RTEMS during initialization. Each device driver may contain the |
---|
| 43 | following entry points: |
---|
[ae68ff0] | 44 | |
---|
| 45 | @itemize @bullet |
---|
| 46 | @item Initialization |
---|
| 47 | @item Open |
---|
| 48 | @item Close |
---|
| 49 | @item Read |
---|
| 50 | @item Write |
---|
| 51 | @item Control |
---|
| 52 | @end itemize |
---|
| 53 | |
---|
| 54 | If the device driver does not support a particular |
---|
| 55 | entry point, then that entry in the Configuration Table should |
---|
[75e22db] | 56 | be NULL. RTEMS will return |
---|
| 57 | @code{@value{RPREFIX}SUCCESSFUL} as the executive's and |
---|
[ae68ff0] | 58 | zero (0) as the device driver's return code for these device |
---|
| 59 | driver entry points. |
---|
| 60 | |
---|
[6d00095] | 61 | Applications can register and unregister drivers with the RTEMS I/O |
---|
| 62 | manager avoiding the need to have all drivers statically defined and |
---|
| 63 | linked into this table. |
---|
| 64 | |
---|
| 65 | The @file{confdefs.h} entry @code{CONFIGURE_MAXIMUM_DRIVERS} configures |
---|
| 66 | the number of driver slots available to the application. |
---|
| 67 | |
---|
[ae68ff0] | 68 | @subsection Major and Minor Device Numbers |
---|
| 69 | |
---|
[169502e] | 70 | @cindex major device number |
---|
| 71 | @cindex minor device number |
---|
| 72 | |
---|
[ae68ff0] | 73 | Each call to the I/O manager must provide a device's |
---|
| 74 | major and minor numbers as arguments. The major number is the |
---|
| 75 | index of the requested driver's entry points in the Device |
---|
| 76 | Driver Table, and is used to select a specific device driver. |
---|
| 77 | The exact usage of the minor number is driver specific, but is |
---|
| 78 | commonly used to distinguish between a number of devices |
---|
| 79 | controlled by the same driver. |
---|
| 80 | |
---|
[adee5979] | 81 | @findex rtems_device_major_number |
---|
| 82 | @findex rtems_device_minor_number |
---|
| 83 | |
---|
| 84 | The data types @code{@value{DIRPREFIX}device_major_number} and |
---|
| 85 | @code{@value{DIRPREFIX}device_minor_number} are used to |
---|
| 86 | manipulate device major and minor numbers, respectively. |
---|
| 87 | |
---|
[ae68ff0] | 88 | @subsection Device Names |
---|
| 89 | |
---|
[169502e] | 90 | @cindex device names |
---|
| 91 | |
---|
[ae68ff0] | 92 | The I/O Manager provides facilities to associate a |
---|
| 93 | name with a particular device. Directives are provided to |
---|
| 94 | register the name of a device and to look up the major/minor |
---|
| 95 | number pair associated with a device name. |
---|
| 96 | |
---|
| 97 | @subsection Device Driver Environment |
---|
| 98 | |
---|
| 99 | Application developers, as well as device driver |
---|
| 100 | developers, must be aware of the following regarding the RTEMS |
---|
| 101 | I/O Manager: |
---|
| 102 | |
---|
| 103 | @itemize @bullet |
---|
| 104 | @item A device driver routine executes in the context of the |
---|
| 105 | invoking task. Thus if the driver blocks, the invoking task |
---|
| 106 | blocks. |
---|
| 107 | |
---|
| 108 | @item The device driver is free to change the modes of the |
---|
| 109 | invoking task, although the driver should restore them to their |
---|
| 110 | original values. |
---|
| 111 | |
---|
| 112 | @item Device drivers may be invoked from ISRs. |
---|
| 113 | |
---|
| 114 | @item Only local device drivers are accessible through the I/O |
---|
| 115 | manager. |
---|
| 116 | |
---|
| 117 | @item A device driver routine may invoke all other RTEMS |
---|
| 118 | directives, including I/O directives, on both local and global |
---|
| 119 | objects. |
---|
| 120 | |
---|
| 121 | @end itemize |
---|
| 122 | |
---|
| 123 | Although the RTEMS I/O manager provides a framework |
---|
| 124 | for device drivers, it makes no assumptions regarding the |
---|
| 125 | construction or operation of a device driver. |
---|
| 126 | |
---|
[75db5285] | 127 | @subsection Runtime Driver Registration |
---|
[6d00095] | 128 | |
---|
| 129 | @cindex runtime driver registration |
---|
| 130 | |
---|
| 131 | Board support package and application developers can select wether a |
---|
| 132 | device driver is statically entered into the default device table or |
---|
| 133 | registered at runtime. |
---|
| 134 | |
---|
| 135 | Dynamic registration helps applications where: |
---|
| 136 | |
---|
| 137 | @enumerate |
---|
| 138 | @item The BSP and kernel libraries are common to a range of applications |
---|
| 139 | for a specific target platform. An application may be built upon a |
---|
| 140 | common library with all drivers. The application selects and registers |
---|
| 141 | the drivers. Uniform driver name lookup protects the application. |
---|
| 142 | @item The type and range of drivers may vary as the application probes a |
---|
| 143 | bus during initialization. |
---|
| 144 | @item Support for hot swap bus system such as Compact PCI. |
---|
| 145 | @item Support for runtime loadable driver modules. |
---|
| 146 | @end enumerate |
---|
| 147 | |
---|
[ae68ff0] | 148 | @subsection Device Driver Interface |
---|
| 149 | |
---|
[169502e] | 150 | @cindex device driver interface |
---|
| 151 | |
---|
[ae68ff0] | 152 | When an application invokes an I/O manager directive, |
---|
| 153 | RTEMS determines which device driver entry point must be |
---|
| 154 | invoked. The information passed by the application to RTEMS is |
---|
| 155 | then passed to the correct device driver entry point. RTEMS |
---|
| 156 | will invoke each device driver entry point assuming it is |
---|
| 157 | compatible with the following prototype: |
---|
| 158 | |
---|
[61389eac] | 159 | @ifset is-C |
---|
[ae68ff0] | 160 | @example |
---|
| 161 | rtems_device_driver io_entry( |
---|
| 162 | rtems_device_major_number major, |
---|
| 163 | rtems_device_minor_number minor, |
---|
| 164 | void *argument_block |
---|
| 165 | ); |
---|
| 166 | @end example |
---|
[61389eac] | 167 | @end ifset |
---|
[ae68ff0] | 168 | |
---|
[61389eac] | 169 | @ifset is-Ada |
---|
| 170 | @example |
---|
[1b03eed] | 171 | NOT SUPPORTED FROM Ada BINDING |
---|
[61389eac] | 172 | @end example |
---|
| 173 | @end ifset |
---|
[ae68ff0] | 174 | |
---|
| 175 | The format and contents of the parameter block are |
---|
| 176 | device driver and entry point dependent. |
---|
| 177 | |
---|
| 178 | It is recommended that a device driver avoid |
---|
| 179 | generating error codes which conflict with those used by |
---|
| 180 | application components. A common technique used to generate |
---|
| 181 | driver specific error codes is to make the most significant part |
---|
| 182 | of the status indicate a driver specific code. |
---|
| 183 | |
---|
| 184 | @subsection Device Driver Initialization |
---|
| 185 | |
---|
| 186 | RTEMS automatically initializes all device drivers |
---|
[68f54e1] | 187 | when multitasking is initiated via the |
---|
| 188 | @code{@value{DIRPREFIX}initialize_executive} |
---|
[ae68ff0] | 189 | directive. RTEMS initializes the device drivers by invoking |
---|
| 190 | each device driver initialization entry point with the following |
---|
| 191 | parameters: |
---|
| 192 | |
---|
| 193 | @table @asis |
---|
| 194 | @item major |
---|
| 195 | the major device number for this device driver. |
---|
| 196 | |
---|
| 197 | @item minor |
---|
| 198 | zero. |
---|
| 199 | |
---|
| 200 | @item argument_block |
---|
| 201 | will point to the Configuration Table. |
---|
| 202 | |
---|
| 203 | @end table |
---|
| 204 | |
---|
| 205 | The returned status will be ignored by RTEMS. If the driver |
---|
| 206 | cannot successfully initialize the device, then it should invoke |
---|
| 207 | the fatal_error_occurred directive. |
---|
| 208 | |
---|
| 209 | @section Operations |
---|
[20515fc] | 210 | |
---|
[ae68ff0] | 211 | @subsection Register and Lookup Name |
---|
| 212 | |
---|
[75e22db] | 213 | The @code{@value{DIRPREFIX}io_register} directive associates a name with the |
---|
[ae68ff0] | 214 | specified device (i.e. major/minor number pair). Device names |
---|
| 215 | are typically registered as part of the device driver |
---|
[75e22db] | 216 | initialization sequence. The @code{@value{DIRPREFIX}io_lookup} |
---|
| 217 | directive is used to |
---|
[ae68ff0] | 218 | determine the major/minor number pair associated with the |
---|
| 219 | specified device name. The use of these directives frees the |
---|
| 220 | application from being dependent on the arbitrary assignment of |
---|
| 221 | major numbers in a particular application. No device naming |
---|
| 222 | conventions are dictated by RTEMS. |
---|
| 223 | |
---|
| 224 | @subsection Accessing an Device Driver |
---|
| 225 | |
---|
| 226 | The I/O manager provides directives which enable the |
---|
| 227 | application program to utilize device drivers in a standard |
---|
| 228 | manner. There is a direct correlation between the RTEMS I/O |
---|
[75e22db] | 229 | manager directives |
---|
| 230 | @code{@value{DIRPREFIX}io_initialize}, |
---|
| 231 | @code{@value{DIRPREFIX}io_open}, |
---|
| 232 | @code{@value{DIRPREFIX}io_close}, |
---|
| 233 | @code{@value{DIRPREFIX}io_read}, |
---|
| 234 | @code{@value{DIRPREFIX}io_write}, and |
---|
| 235 | @code{@value{DIRPREFIX}io_control} |
---|
| 236 | and the underlying device driver entry points. |
---|
[ae68ff0] | 237 | |
---|
| 238 | @section Directives |
---|
| 239 | |
---|
| 240 | This section details the I/O manager's directives. A |
---|
| 241 | subsection is dedicated to each of this manager's directives and |
---|
| 242 | describes the calling sequence, related constants, usage, and |
---|
| 243 | status codes. |
---|
| 244 | |
---|
[6d00095] | 245 | @c |
---|
| 246 | @c |
---|
| 247 | @c |
---|
| 248 | @page |
---|
| 249 | @subsection IO_REGISTER_DRIVER - Register a device driver |
---|
| 250 | |
---|
| 251 | @cindex register a device driver |
---|
| 252 | |
---|
| 253 | @subheading CALLING SEQUENCE: |
---|
| 254 | |
---|
| 255 | @ifset is-C |
---|
| 256 | @findex rtems_io_register_driver |
---|
| 257 | @example |
---|
| 258 | rtems_status_code rtems_io_register_driver( |
---|
| 259 | rtems_device_major_number major, |
---|
| 260 | rtems_driver_address_table *driver_table, |
---|
| 261 | rtems_device_major_number *registered_major |
---|
| 262 | ); |
---|
| 263 | @end example |
---|
| 264 | @end ifset |
---|
| 265 | |
---|
| 266 | @ifset is-Ada |
---|
| 267 | @example |
---|
[1b03eed] | 268 | NOT SUPPORTED FROM Ada BINDING |
---|
[6d00095] | 269 | @end example |
---|
| 270 | @end ifset |
---|
| 271 | |
---|
| 272 | @subheading DIRECTIVE STATUS CODES: |
---|
| 273 | @code{@value{RPREFIX}SUCCESSFUL} - successfully registered@* |
---|
[6829e03] | 274 | @code{@value{RPREFIX}INVALID_ADDRESS} - invalid registered major pointer@* |
---|
| 275 | @code{@value{RPREFIX}INVALID_ADDRESS} - invalid driver table@* |
---|
[6d00095] | 276 | @code{@value{RPREFIX}INVALID_NUMBER} - invalid major device number@* |
---|
| 277 | @code{@value{RPREFIX}TOO_MANY} - no available major device table slot@* |
---|
| 278 | @code{@value{RPREFIX}RESOURCE_IN_USE} - major device number entry in use |
---|
| 279 | |
---|
| 280 | @subheading DESCRIPTION: |
---|
| 281 | |
---|
| 282 | This directive attempts to add a new device driver to the Device Driver |
---|
| 283 | Table. The user can specify a specific major device number via the |
---|
| 284 | directive's @code{major} parameter, or let the registration routine find |
---|
| 285 | the next available major device number by specifing a major number of |
---|
| 286 | @code{0}. The selected major device number is returned via the |
---|
| 287 | @code{registered_major} directive parameter. The directive automatically |
---|
| 288 | allocation major device numbers from the highest value down. |
---|
| 289 | |
---|
| 290 | This directive automatically invokes the IO_INITIALIZE directive if |
---|
| 291 | the driver address table has an initialization and open entry. |
---|
| 292 | |
---|
| 293 | The directive returns @value{RPREFIX}TOO_MANY if Device Driver Table is |
---|
| 294 | full, and @value{RPREFIX}RESOURCE_IN_USE if a specific major device |
---|
| 295 | number is requested and it is already in use. |
---|
| 296 | |
---|
| 297 | @subheading NOTES: |
---|
| 298 | |
---|
| 299 | The Device Driver Table size is specified in the Configuration Table |
---|
| 300 | condiguration. This needs to be set to maximum size the application |
---|
| 301 | requires. |
---|
| 302 | |
---|
| 303 | |
---|
| 304 | @c |
---|
| 305 | @c |
---|
| 306 | @c |
---|
| 307 | @page |
---|
| 308 | @subsection IO_UNREGISTER_DRIVER - Unregister a device driver |
---|
| 309 | |
---|
| 310 | @cindex unregister a device driver |
---|
| 311 | |
---|
| 312 | @subheading CALLING SEQUENCE: |
---|
| 313 | |
---|
| 314 | @ifset is-C |
---|
| 315 | @findex rtems_io_unregister_driver |
---|
| 316 | @example |
---|
| 317 | rtems_status_code rtems_io_register_driver( |
---|
| 318 | rtems_device_major_number major |
---|
| 319 | ); |
---|
| 320 | @end example |
---|
| 321 | @end ifset |
---|
| 322 | |
---|
| 323 | @ifset is-Ada |
---|
| 324 | @example |
---|
[1b03eed] | 325 | NOT SUPPORTED FROM Ada BINDING |
---|
[6d00095] | 326 | @end example |
---|
| 327 | @end ifset |
---|
| 328 | |
---|
| 329 | @subheading DIRECTIVE STATUS CODES: |
---|
| 330 | @code{@value{RPREFIX}SUCCESSFUL} - successfully registered@* |
---|
| 331 | @code{@value{RPREFIX}INVALID_NUMBER} - invalid major device number |
---|
| 332 | |
---|
| 333 | @subheading DESCRIPTION: |
---|
| 334 | |
---|
| 335 | This directive removes a device driver from the Device Driver Table. |
---|
| 336 | |
---|
| 337 | @subheading NOTES: |
---|
| 338 | |
---|
| 339 | Currently no specific checks are made and the driver is not closed. |
---|
| 340 | |
---|
| 341 | |
---|
[169502e] | 342 | @c |
---|
| 343 | @c |
---|
| 344 | @c |
---|
[ae68ff0] | 345 | @page |
---|
| 346 | @subsection IO_INITIALIZE - Initialize a device driver |
---|
| 347 | |
---|
[169502e] | 348 | @cindex initialize a device driver |
---|
| 349 | |
---|
[ae68ff0] | 350 | @subheading CALLING SEQUENCE: |
---|
| 351 | |
---|
[61389eac] | 352 | @ifset is-C |
---|
[169502e] | 353 | @findex rtems_io_initialize |
---|
[ae68ff0] | 354 | @example |
---|
| 355 | rtems_status_code rtems_io_initialize( |
---|
| 356 | rtems_device_major_number major, |
---|
| 357 | rtems_device_minor_number minor, |
---|
| 358 | void *argument |
---|
| 359 | ); |
---|
| 360 | @end example |
---|
[61389eac] | 361 | @end ifset |
---|
| 362 | |
---|
| 363 | @ifset is-Ada |
---|
| 364 | @example |
---|
[1b03eed] | 365 | NOT SUPPORTED FROM Ada BINDING |
---|
[61389eac] | 366 | @end example |
---|
| 367 | @end ifset |
---|
[ae68ff0] | 368 | |
---|
| 369 | @subheading DIRECTIVE STATUS CODES: |
---|
[f331481c] | 370 | @code{@value{RPREFIX}SUCCESSFUL} - successfully initialized@* |
---|
| 371 | @code{@value{RPREFIX}INVALID_NUMBER} - invalid major device number |
---|
[ae68ff0] | 372 | |
---|
| 373 | @subheading DESCRIPTION: |
---|
| 374 | |
---|
| 375 | This directive calls the device driver initialization |
---|
| 376 | routine specified in the Device Driver Table for this major |
---|
| 377 | number. This directive is automatically invoked for each device |
---|
| 378 | driver when multitasking is initiated via the |
---|
| 379 | initialize_executive directive. |
---|
| 380 | |
---|
| 381 | A device driver initialization module is responsible |
---|
| 382 | for initializing all hardware and data structures associated |
---|
| 383 | with a device. If necessary, it can allocate memory to be used |
---|
| 384 | during other operations. |
---|
| 385 | |
---|
| 386 | @subheading NOTES: |
---|
| 387 | |
---|
| 388 | This directive may or may not cause the calling task |
---|
| 389 | to be preempted. This is dependent on the device driver being |
---|
| 390 | initialized. |
---|
| 391 | |
---|
[169502e] | 392 | @c |
---|
| 393 | @c |
---|
| 394 | @c |
---|
[ae68ff0] | 395 | @page |
---|
| 396 | @subsection IO_REGISTER_NAME - Register a device |
---|
| 397 | |
---|
[169502e] | 398 | @cindex register device |
---|
| 399 | |
---|
[ae68ff0] | 400 | @subheading CALLING SEQUENCE: |
---|
| 401 | |
---|
[61389eac] | 402 | @ifset is-C |
---|
[169502e] | 403 | @findex rtems_io_register_name |
---|
[ae68ff0] | 404 | @example |
---|
| 405 | rtems_status_code rtems_io_register_name( |
---|
[dec0a35] | 406 | const char *name, |
---|
[ae68ff0] | 407 | rtems_device_major_number major, |
---|
| 408 | rtems_device_minor_number minor |
---|
| 409 | ); |
---|
| 410 | @end example |
---|
[61389eac] | 411 | @end ifset |
---|
| 412 | |
---|
| 413 | @ifset is-Ada |
---|
| 414 | @example |
---|
[1b03eed] | 415 | NOT SUPPORTED FROM Ada BINDING |
---|
[61389eac] | 416 | @end example |
---|
| 417 | @end ifset |
---|
[ae68ff0] | 418 | |
---|
| 419 | @subheading DIRECTIVE STATUS CODES: |
---|
[f331481c] | 420 | @code{@value{RPREFIX}SUCCESSFUL} - successfully initialized@* |
---|
| 421 | @code{@value{RPREFIX}TOO_MANY} - too many devices registered |
---|
[ae68ff0] | 422 | |
---|
| 423 | @subheading DESCRIPTION: |
---|
| 424 | |
---|
| 425 | This directive associates name with the specified |
---|
| 426 | major/minor number pair. |
---|
| 427 | |
---|
| 428 | @subheading NOTES: |
---|
| 429 | |
---|
| 430 | This directive will not cause the calling task to be |
---|
| 431 | preempted. |
---|
| 432 | |
---|
[169502e] | 433 | @c |
---|
| 434 | @c |
---|
| 435 | @c |
---|
[ae68ff0] | 436 | @page |
---|
| 437 | @subsection IO_LOOKUP_NAME - Lookup a device |
---|
| 438 | |
---|
[169502e] | 439 | @cindex lookup device major and minor number |
---|
| 440 | |
---|
[ae68ff0] | 441 | @subheading CALLING SEQUENCE: |
---|
| 442 | |
---|
[61389eac] | 443 | @ifset is-C |
---|
[169502e] | 444 | @findex rtems_io_lookup_name |
---|
[ae68ff0] | 445 | @example |
---|
[61389eac] | 446 | rtems_status_code rtems_io_lookup_name( |
---|
[ae68ff0] | 447 | const char *name, |
---|
[50381010] | 448 | rtems_driver_name_t *device_info |
---|
[ae68ff0] | 449 | ); |
---|
| 450 | @end example |
---|
[61389eac] | 451 | @end ifset |
---|
| 452 | |
---|
| 453 | @ifset is-Ada |
---|
| 454 | @example |
---|
[1b03eed] | 455 | NOT SUPPORTED FROM Ada BINDING |
---|
[61389eac] | 456 | @end example |
---|
| 457 | @end ifset |
---|
[ae68ff0] | 458 | |
---|
| 459 | @subheading DIRECTIVE STATUS CODES: |
---|
[f331481c] | 460 | @code{@value{RPREFIX}SUCCESSFUL} - successfully initialized@* |
---|
| 461 | @code{@value{RPREFIX}UNSATISFIED} - name not registered |
---|
[ae68ff0] | 462 | |
---|
| 463 | @subheading DESCRIPTION: |
---|
| 464 | |
---|
| 465 | This directive returns the major/minor number pair |
---|
[f4ab3d3] | 466 | associated with the given device name in @code{device_info}. |
---|
[ae68ff0] | 467 | |
---|
| 468 | @subheading NOTES: |
---|
| 469 | |
---|
| 470 | This directive will not cause the calling task to be |
---|
| 471 | preempted. |
---|
| 472 | |
---|
[169502e] | 473 | @c |
---|
| 474 | @c |
---|
| 475 | @c |
---|
[ae68ff0] | 476 | @page |
---|
| 477 | @subsection IO_OPEN - Open a device |
---|
| 478 | |
---|
[169502e] | 479 | @cindex open a devive |
---|
| 480 | |
---|
[ae68ff0] | 481 | @subheading CALLING SEQUENCE: |
---|
| 482 | |
---|
[61389eac] | 483 | @ifset is-C |
---|
[169502e] | 484 | @findex rtems_io_open |
---|
[ae68ff0] | 485 | @example |
---|
| 486 | rtems_status_code rtems_io_open( |
---|
| 487 | rtems_device_major_number major, |
---|
| 488 | rtems_device_minor_number minor, |
---|
| 489 | void *argument |
---|
| 490 | ); |
---|
| 491 | @end example |
---|
[61389eac] | 492 | @end ifset |
---|
| 493 | |
---|
| 494 | @ifset is-Ada |
---|
| 495 | @example |
---|
[1b03eed] | 496 | NOT SUPPORTED FROM Ada BINDING |
---|
[61389eac] | 497 | @end example |
---|
| 498 | @end ifset |
---|
[ae68ff0] | 499 | |
---|
| 500 | @subheading DIRECTIVE STATUS CODES: |
---|
[f331481c] | 501 | @code{@value{RPREFIX}SUCCESSFUL} - successfully initialized@* |
---|
| 502 | @code{@value{RPREFIX}INVALID_NUMBER} - invalid major device number |
---|
[ae68ff0] | 503 | |
---|
| 504 | @subheading DESCRIPTION: |
---|
| 505 | |
---|
| 506 | This directive calls the device driver open routine |
---|
| 507 | specified in the Device Driver Table for this major number. The |
---|
| 508 | open entry point is commonly used by device drivers to provide |
---|
| 509 | exclusive access to a device. |
---|
| 510 | |
---|
| 511 | @subheading NOTES: |
---|
| 512 | |
---|
| 513 | This directive may or may not cause the calling task |
---|
| 514 | to be preempted. This is dependent on the device driver being |
---|
| 515 | invoked. |
---|
| 516 | |
---|
[169502e] | 517 | @c |
---|
| 518 | @c |
---|
| 519 | @c |
---|
[ae68ff0] | 520 | @page |
---|
| 521 | @subsection IO_CLOSE - Close a device |
---|
| 522 | |
---|
[169502e] | 523 | @cindex close a device |
---|
| 524 | |
---|
[ae68ff0] | 525 | @subheading CALLING SEQUENCE: |
---|
| 526 | |
---|
[61389eac] | 527 | @ifset is-C |
---|
[169502e] | 528 | @findex rtems_io_close |
---|
[ae68ff0] | 529 | @example |
---|
| 530 | rtems_status_code rtems_io_close( |
---|
| 531 | rtems_device_major_number major, |
---|
| 532 | rtems_device_minor_number minor, |
---|
| 533 | void *argument |
---|
| 534 | ); |
---|
| 535 | @end example |
---|
[61389eac] | 536 | @end ifset |
---|
| 537 | |
---|
| 538 | @ifset is-Ada |
---|
| 539 | @example |
---|
[1b03eed] | 540 | NOT SUPPORTED FROM Ada BINDING |
---|
[61389eac] | 541 | @end example |
---|
| 542 | @end ifset |
---|
[ae68ff0] | 543 | |
---|
| 544 | @subheading DIRECTIVE STATUS CODES: |
---|
[f331481c] | 545 | @code{@value{RPREFIX}SUCCESSFUL} - successfully initialized@* |
---|
| 546 | @code{@value{RPREFIX}INVALID_NUMBER} - invalid major device number |
---|
[ae68ff0] | 547 | |
---|
| 548 | @subheading DESCRIPTION: |
---|
| 549 | |
---|
| 550 | This directive calls the device driver close routine |
---|
| 551 | specified in the Device Driver Table for this major number. The |
---|
| 552 | close entry point is commonly used by device drivers to |
---|
| 553 | relinquish exclusive access to a device. |
---|
| 554 | |
---|
| 555 | @subheading NOTES: |
---|
| 556 | |
---|
| 557 | This directive may or may not cause the calling task |
---|
| 558 | to be preempted. This is dependent on the device driver being |
---|
| 559 | invoked. |
---|
| 560 | |
---|
[169502e] | 561 | @c |
---|
| 562 | @c |
---|
| 563 | @c |
---|
[ae68ff0] | 564 | @page |
---|
| 565 | @subsection IO_READ - Read from a device |
---|
| 566 | |
---|
[169502e] | 567 | @cindex read from a device |
---|
| 568 | |
---|
[ae68ff0] | 569 | @subheading CALLING SEQUENCE: |
---|
| 570 | |
---|
[61389eac] | 571 | @ifset is-C |
---|
[169502e] | 572 | @findex rtems_io_read |
---|
[ae68ff0] | 573 | @example |
---|
| 574 | rtems_status_code rtems_io_read( |
---|
| 575 | rtems_device_major_number major, |
---|
| 576 | rtems_device_minor_number minor, |
---|
| 577 | void *argument |
---|
| 578 | ); |
---|
| 579 | @end example |
---|
[61389eac] | 580 | @end ifset |
---|
| 581 | |
---|
| 582 | @ifset is-Ada |
---|
| 583 | @example |
---|
[1b03eed] | 584 | NOT SUPPORTED FROM Ada BINDING |
---|
[61389eac] | 585 | @end example |
---|
| 586 | @end ifset |
---|
[ae68ff0] | 587 | |
---|
| 588 | @subheading DIRECTIVE STATUS CODES: |
---|
[f331481c] | 589 | @code{@value{RPREFIX}SUCCESSFUL} - successfully initialized@* |
---|
| 590 | @code{@value{RPREFIX}INVALID_NUMBER} - invalid major device number |
---|
[ae68ff0] | 591 | |
---|
| 592 | @subheading DESCRIPTION: |
---|
| 593 | |
---|
| 594 | This directive calls the device driver read routine |
---|
| 595 | specified in the Device Driver Table for this major number. |
---|
| 596 | Read operations typically require a buffer address as part of |
---|
| 597 | the argument parameter block. The contents of this buffer will |
---|
| 598 | be replaced with data from the device. |
---|
| 599 | |
---|
| 600 | @subheading NOTES: |
---|
| 601 | |
---|
| 602 | This directive may or may not cause the calling task |
---|
| 603 | to be preempted. This is dependent on the device driver being |
---|
| 604 | invoked. |
---|
| 605 | |
---|
[169502e] | 606 | @c |
---|
| 607 | @c |
---|
| 608 | @c |
---|
[ae68ff0] | 609 | @page |
---|
| 610 | @subsection IO_WRITE - Write to a device |
---|
| 611 | |
---|
[169502e] | 612 | @cindex write to a device |
---|
| 613 | |
---|
[ae68ff0] | 614 | @subheading CALLING SEQUENCE: |
---|
| 615 | |
---|
[61389eac] | 616 | @ifset is-C |
---|
[169502e] | 617 | @findex rtems_io_write |
---|
[ae68ff0] | 618 | @example |
---|
| 619 | rtems_status_code rtems_io_write( |
---|
| 620 | rtems_device_major_number major, |
---|
| 621 | rtems_device_minor_number minor, |
---|
| 622 | void *argument |
---|
| 623 | ); |
---|
| 624 | @end example |
---|
[61389eac] | 625 | @end ifset |
---|
| 626 | |
---|
| 627 | @ifset is-Ada |
---|
| 628 | @example |
---|
[1b03eed] | 629 | NOT SUPPORTED FROM Ada BINDING |
---|
[61389eac] | 630 | @end example |
---|
| 631 | @end ifset |
---|
[ae68ff0] | 632 | |
---|
| 633 | @subheading DIRECTIVE STATUS CODES: |
---|
[f331481c] | 634 | @code{@value{RPREFIX}SUCCESSFUL} - successfully initialized@* |
---|
| 635 | @code{@value{RPREFIX}INVALID_NUMBER} - invalid major device number |
---|
[ae68ff0] | 636 | |
---|
| 637 | @subheading DESCRIPTION: |
---|
| 638 | |
---|
| 639 | This directive calls the device driver write routine |
---|
| 640 | specified in the Device Driver Table for this major number. |
---|
| 641 | Write operations typically require a buffer address as part of |
---|
| 642 | the argument parameter block. The contents of this buffer will |
---|
| 643 | be sent to the device. |
---|
| 644 | |
---|
| 645 | @subheading NOTES: |
---|
| 646 | |
---|
| 647 | This directive may or may not cause the calling task |
---|
| 648 | to be preempted. This is dependent on the device driver being |
---|
| 649 | invoked. |
---|
| 650 | |
---|
[169502e] | 651 | @c |
---|
| 652 | @c |
---|
| 653 | @c |
---|
[ae68ff0] | 654 | @page |
---|
| 655 | @subsection IO_CONTROL - Special device services |
---|
| 656 | |
---|
[169502e] | 657 | @cindex special device services |
---|
| 658 | @cindex IO Control |
---|
| 659 | |
---|
[ae68ff0] | 660 | @subheading CALLING SEQUENCE: |
---|
| 661 | |
---|
[61389eac] | 662 | @ifset is-C |
---|
[169502e] | 663 | @findex rtems_io_control |
---|
[ae68ff0] | 664 | @example |
---|
| 665 | rtems_status_code rtems_io_control( |
---|
| 666 | rtems_device_major_number major, |
---|
| 667 | rtems_device_minor_number minor, |
---|
| 668 | void *argument |
---|
| 669 | ); |
---|
| 670 | @end example |
---|
[61389eac] | 671 | @end ifset |
---|
| 672 | |
---|
| 673 | @ifset is-Ada |
---|
| 674 | @example |
---|
[1b03eed] | 675 | NOT SUPPORTED FROM Ada BINDING |
---|
[61389eac] | 676 | @end example |
---|
| 677 | @end ifset |
---|
[ae68ff0] | 678 | |
---|
| 679 | @subheading DIRECTIVE STATUS CODES: |
---|
[f331481c] | 680 | @code{@value{RPREFIX}SUCCESSFUL} - successfully initialized@* |
---|
| 681 | @code{@value{RPREFIX}INVALID_NUMBER} - invalid major device number |
---|
[ae68ff0] | 682 | |
---|
| 683 | @subheading DESCRIPTION: |
---|
| 684 | |
---|
| 685 | This directive calls the device driver I/O control |
---|
| 686 | routine specified in the Device Driver Table for this major |
---|
| 687 | number. The exact functionality of the driver entry called by |
---|
| 688 | this directive is driver dependent. It should not be assumed |
---|
| 689 | that the control entries of two device drivers are compatible. |
---|
| 690 | For example, an RS-232 driver I/O control operation may change |
---|
| 691 | the baud rate of a serial line, while an I/O control operation |
---|
| 692 | for a floppy disk driver may cause a seek operation. |
---|
| 693 | |
---|
| 694 | @subheading NOTES: |
---|
| 695 | |
---|
| 696 | This directive may or may not cause the calling task |
---|
| 697 | to be preempted. This is dependent on the device driver being |
---|
| 698 | invoked. |
---|
| 699 | |
---|
| 700 | |
---|
| 701 | |
---|