summaryrefslogtreecommitdiffstats
path: root/new_chapters/new_chapters.rst
blob: b92e7f810ddaa3b7ca8dd859440c762a7fc19393 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
:orphan:



.. COMMENT: %**end of header

.. COMMENT: COPYRIGHT (c) 1989-2013.

.. COMMENT: On-Line Applications Research Corporation (OAR).

.. COMMENT: All rights reserved.

.. COMMENT: Master file for the C User's Guide

.. COMMENT: Joel's Questions

.. COMMENT: 1.  Why does paragraphindent only impact makeinfo?

.. COMMENT: 2.  Why does paragraphindent show up in HTML?

.. COMMENT: COPYRIGHT (c) 1988-2002.

.. COMMENT: On-Line Applications Research Corporation (OAR).

.. COMMENT: All rights reserved.

.. COMMENT: The following determines which set of the tables and figures we will use.

.. COMMENT: We default to ASCII but if available TeX or HTML versions will

.. COMMENT: be used instead.

.. COMMENT: @clear use-html

.. COMMENT: @clear use-tex

.. COMMENT: The following variable says to use texinfo or html for the two column

.. COMMENT: texinfo tables.  For somethings the format does not look good in html.

.. COMMENT: With our adjustment to the left column in TeX, it nearly always looks

.. COMMENT: good printed.

.. COMMENT: Custom whitespace adjustments.  We could fiddle a bit more.

.. COMMENT: variable substitution info:

.. COMMENT: Note: At the moment we do not document the Ada interface but by building

.. COMMENT: in the infrastructure Florist support should be simple to add.

.. COMMENT: the language is @value{LANGUAGE}

.. COMMENT: NOTE:  don't use underscore in the name

.. COMMENT: Title Page Stuff

.. COMMENT: I don't really like having a short title page.  -joel

.. COMMENT: @shorttitlepage New Chapters

============
New Chapters
============

.. COMMENT: COPYRIGHT (c) 1988-2015.

.. COMMENT: On-Line Applications Research Corporation (OAR).

.. COMMENT: All rights reserved.

.. COMMENT: The following puts a space somewhere on an otherwise empty page so we

.. COMMENT: can force the copyright description onto a left hand page.

COPYRIGHT © 1988 - 2015.

On-Line Applications Research Corporation (OAR).

The authors have used their best efforts in preparing
this material.  These efforts include the development, research,
and testing of the theories and programs to determine their
effectiveness.  No warranty of any kind, expressed or implied,
with regard to the software or the material contained in this
document is provided.  No liability arising out of the
application or use of any product described in this document is
assumed.  The authors reserve the right to revise this material
and to make changes from time to time in the content hereof
without obligation to notify anyone of such revision or changes.

The RTEMS Project is hosted at http://www.rtems.org.  Any
inquiries concerning RTEMS, its related support components, or its
documentation should be directed to the Community Project hosted athttp://www.rtems.org.

Any inquiries for commercial services including training, support, custom
development, application development assistance should be directed tohttp://www.rtems.com.

.. COMMENT: This prevents a black box from being printed on "overflow" lines.

.. COMMENT: The alternative is to rework a sentence to avoid this problem.

RTEMS POSIX API User’s Guide
############################

.. COMMENT: COPYRIGHT (c) 1988-2002.

.. COMMENT: On-Line Applications Research Corporation (OAR).

.. COMMENT: All rights reserved.

Error Reporting Support
#######################

Introduction
============

These error reporting facilities are an RTEMS support
component that provide convenient facilities for handling
error conditions in an RTEMS application.
of each task using a period.  The services provided by the error
reporting support component are:

- ``rtems_error`` - Report an Error

- ``rtems_panic`` - Report an Error and Panic

- ``rtems_status_text`` - ASCII Version of RTEMS Status

Background
==========

Error Handling in an Embedded System
------------------------------------

Error handling in an embedded system is a difficult problem.  If the error
is severe, then the only recourse is to shut the system down in a safe
manner.  Other errors can be detected and compensated for.  The
error reporting routines in this support component – ``rtems_error``
and ``rtems_panic`` assume that if the error is severe enough,
then the system should be shutdown.  If a simple shutdown with
some basic diagnostic information is not sufficient, then
these routines should not be used in that particular system.  In this case,
use the ``rtems_status_text`` routine to construct an application
specific error reporting routine.

Operations
==========

Reporting an Error
------------------

The ``rtems_error`` and ``rtems_panic`` routines
can be used to print some diagnostic information and
shut the system down.  The ``rtems_error`` routine
is invoked with a user specified error level indicator.
This error indicator is used to determine if the system
should be shutdown after reporting this error.

Routines
========

This section details the error reporting support compenent’s routine.
A subsection is dedicated to each of this manager’s routines
and describes the calling sequence, related constants, usage,
and status codes.

rtems_status_text - ASCII Version of RTEMS Status
-------------------------------------------------

**CALLING SEQUENCE:**

.. code:: c

    const char \*rtems_status_text(
    rtems_status_code status
    );

**STATUS CODES:**

Returns a pointer to a constant string that describes the given
RTEMS status code.

**DESCRIPTION:**

This routine returns a pointer to a string that describes
the RTEMS status code specified by ``status``.

**NOTES:**

NONE

rtems_error - Report an Error
-----------------------------

**CALLING SEQUENCE:**

.. code:: c

    int rtems_error(
    int         error_code,
    const char \*printf_format,
    ...
    );

**STATUS CODES:**

Returns the number of characters written.

**DESCRIPTION:**

This routine prints the requested information as specified by the``printf_format`` parameter and the zero or more optional arguments
following that parameter.  The ``error_code`` parameter is an error
number with either ``RTEMS_ERROR_PANIC`` or ``RTEMS_ERROR_ABORT``
bitwise or’ed with it.  If the ``RTEMS_ERROR_PANIC`` bit is set, then
then the system is system is shutdown via a call to ``_exit``.
If the ``RTEMS_ERROR_ABORT`` bit is set, then
then the system is system is shutdown via a call to ``abort``.

**NOTES:**

NONE

rtems_panic - Report an Error and Panic
---------------------------------------

**CALLING SEQUENCE:**

.. code:: c

    int rtems_panic(
    const char \*printf_format,
    ...
    );

**STATUS CODES:**

Returns the number of characters written.

**DESCRIPTION:**

This routine is a wrapper for the ``rtems_error`` routine with
an implied error level of ``RTEMS_ERROR_PANIC``.  See``rtems_error`` for more information.

**NOTES:**

NONE

.. COMMENT: COPYRIGHT (c) 1988-2002.

.. COMMENT: On-Line Applications Research Corporation (OAR).

.. COMMENT: All rights reserved.

Monitor Task
############

Introduction
============

The monitor task is a simple interactive shell that allows the user to
make inquries about he state of various system objects.  The routines
provided by the monitor task manager are:

- ``rtems_monitor_init`` - Initialize the Monitor Task

- ``rtems_monitor_wakeup`` - Wakeup the Monitor Task

Background
==========

There is no background information.

Operations
==========

Initializing the Monitor
------------------------

The monitor is initialized by calling ``rtems_monitor_init``.  When
initialized, the monitor is created as an independent task.  An example
of initializing the monitor is shown below:
.. code:: c

    #include <rtems/monitor.h>
    ...
    rtems_monitor_init(0);

The "0" parameter to the ``rtems_monitor_init`` routine
causes the monitor to immediately enter command mode.
This parameter is a bitfield.  If the monitor is to suspend
itself on startup, then the ``RTEMS_MONITOR_SUSPEND`` bit
should be set.

Routines
========

This section details the monitor task manager’s routines.
A subsection is dedicated to each of this manager’s routines
and describes the calling sequence, related constants, usage,
and status codes.

rtems_monitor_init - Initialize the Monitor Task
------------------------------------------------

**CALLING SEQUENCE:**

.. code:: c

    void rtems_monitor_init(
    unsigned32 monitor_flags
    );

**STATUS CODES: NONE**

**DESCRIPTION:**

This routine initializes the RTEMS monitor task.  The``monitor_flags`` parameter indicates how the server
task is to start.  This parameter is a bitfield and
has the following constants associated with it:

- *RTEMS_MONITOR_SUSPEND* - suspend monitor on startup

- *RTEMS_MONITOR_GLOBAL* - monitor should be global

If the ``RTEMS_MONITOR_SUSPEND`` bit is set, then the
monitor task will suspend itself after it is initialized.
A subsequent call to ``rtems_monitor_wakeup`` will be required
to activate it.

**NOTES:**

The monitor task is created with priority 1.  If there are
application tasks at priority 1, then there may be times
when the monitor task is not executing.

rtems_monitor_wakeup - Wakeup the Monitor Task
----------------------------------------------

**CALLING SEQUENCE:**

.. code:: c

    void rtems_monitor_wakeup( void );

**STATUS CODES: NONE**

**DESCRIPTION:**

This routine is used to activate the monitor task if it is suspended.

**NOTES:**

NONE

Monitor Interactive Commands
============================

The following commands are supported by the monitor task:

- ``help`` - Obtain Help

- ``pause`` - Pause Monitor for a Specified Number of Ticks

- ``exit`` - Invoke a Fatal RTEMS Error

- ``symbol`` - Show Entries from Symbol Table

- ``continue`` - Put Monitor to Sleep Waiting for Explicit Wakeup

- ``config`` - Show System Configuration

- ``itask`` - List Init Tasks

- ``mpci`` - List MPCI Config

- ``task`` - Show Task Information

- ``queue`` - Show Message Queue Information

- ``extension`` - User Extensions

- ``driver`` - Show Information About Named Drivers

- ``dname`` - Show Information About Named Drivers

- ``object`` - Generic Object Information

- ``node`` - Specify Default Node for Commands That Take IDs

help - Obtain Help
------------------

The ``help`` command prints out the list of commands.  If invoked
with a command name as the first argument, detailed help information
on that command is printed.

pause - Pause Monitor for a Specified Number of Ticks
-----------------------------------------------------

The ``pause`` command cause the monitor task to suspend itself
for the specified number of ticks.  If this command is invoked with
no arguments, then the task is suspended for 1 clock tick.

exit - Invoke a Fatal RTEMS Error
---------------------------------

The ``exit`` command invokes ``rtems_error_occurred`` directive
with the specified error code.  If this command is invoked with
no arguments, then the ``rtems_error_occurred`` directive is
invoked with an arbitrary error code.

symbol - Show Entries from Symbol Table
---------------------------------------

The ``symbol`` command lists the specified entries in the symbol table.
If this command is invoked with no arguments, then all the
symbols in the symbol table are printed.

continue - Put Monitor to Sleep Waiting for Explicit Wakeup
-----------------------------------------------------------

The ``continue`` command suspends the monitor task with no timeout.

config - Show System Configuration
----------------------------------

The ``config`` command prints the system configuration.

itask - List Init Tasks
-----------------------

The ``itask`` command lists the tasks in the initialization tasks table.

mpci - List MPCI Config
-----------------------

The ``mpci`` command shows the MPCI configuration information

task - Show Task Information
----------------------------

The ``task`` command prints out information about one or more tasks in
the system.  If invoked with no arguments, then
information on all the tasks in the system is printed.

queue - Show Message Queue Information
--------------------------------------

The ``queue`` command prints out information about one or more
message queues in the system.  If invoked with no arguments, then
information on all the message queues in the system is printed.

extension - User Extensions
---------------------------

The ``extension`` command prints out information about the user
extensions.

driver - Show Information About Named Drivers
---------------------------------------------

The ``driver`` command prints information about the device driver table.

dname - Show Information About Named Drivers
--------------------------------------------

The ``dname`` command prints information about the named device drivers.

object - Generic Object Information
-----------------------------------

The ``object`` command prints information about RTEMS objects.

node - Specify Default Node for Commands That Take IDs
------------------------------------------------------

The ``node`` command sets the default node for commands that look
at object ID ranges.

Command and Variable Index
##########################

There are currently no Command and Variable Index entries.

.. COMMENT: @printindex fn

Concept Index
#############

There are currently no Concept Index entries.

.. COMMENT: @printindex cp