source: rtems/cpukit/include/rtems/monitor.h

Last change on this file was 47e84cb, checked in by Ryan Long <ryan.long@…>, on 04/21/22 at 17:38:31

cpukit/include: Adding file headers and licenses

These files had no file header, copyright, or license. Based on git
history, added appropriate copyright and license.
  • Property mode set to 100644
File size: 19.3 KB
Line 
1/* SPDX-License-Identifier: BSD-2-Clause */
2
3/**
4 * @file
5 *
6 * @brief The RTEMS Monitor Task
7 */
8
9/*
10 * COPYRIGHT (C) 1989-1999 On-Line Applications Research Corporation (OAR).
11 *
12 * Redistribution and use in source and binary forms, with or without
13 * modification, are permitted provided that the following conditions
14 * are met:
15 * 1. Redistributions of source code must retain the above copyright
16 *    notice, this list of conditions and the following disclaimer.
17 * 2. Redistributions in binary form must reproduce the above copyright
18 *    notice, this list of conditions and the following disclaimer in the
19 *    documentation and/or other materials provided with the distribution.
20 *
21 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
22 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
23 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
24 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
25 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
26 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
27 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
28 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
29 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
30 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
31 * POSSIBILITY OF SUCH DAMAGE.
32 */
33
34#ifndef __MONITOR_H
35#define __MONITOR_H
36
37#include <rtems/score/objectimpl.h>
38#include <rtems/error.h>  /* rtems_error() */
39#include <rtems/config.h>
40
41#ifdef __cplusplus
42extern "C" {
43#endif
44
45/* Forward decls from symbols.h */
46typedef struct _rtems_symbol_t rtems_symbol_t;
47typedef struct _rtems_symbol_table_t rtems_symbol_table_t;
48
49/*
50 * Monitor types are derived from rtems object classes
51 */
52
53typedef enum {
54    RTEMS_MONITOR_OBJECT_INVALID   =  OBJECTS_CLASSIC_NO_CLASS,
55    RTEMS_MONITOR_OBJECT_TASK      =  OBJECTS_RTEMS_TASKS,
56    RTEMS_MONITOR_OBJECT_EXTENSION =  OBJECTS_RTEMS_EXTENSIONS,
57    RTEMS_MONITOR_OBJECT_QUEUE     =  OBJECTS_RTEMS_MESSAGE_QUEUES,
58    RTEMS_MONITOR_OBJECT_SEMAPHORE =  OBJECTS_RTEMS_SEMAPHORES,
59    RTEMS_MONITOR_OBJECT_PARTITION =  OBJECTS_RTEMS_PARTITIONS,
60    RTEMS_MONITOR_OBJECT_REGION    =  OBJECTS_RTEMS_REGIONS,
61    RTEMS_MONITOR_OBJECT_PORT      =  OBJECTS_RTEMS_PORTS,
62
63    /* following monitor objects are not known to RTEMS, but
64     * we like to have "types" for them anyway */
65
66    RTEMS_MONITOR_OBJECT_DRIVER    =  OBJECTS_RTEMS_CLASSES_LAST+1,
67    RTEMS_MONITOR_OBJECT_DNAME,
68    RTEMS_MONITOR_OBJECT_CONFIG,
69    RTEMS_MONITOR_OBJECT_INIT_TASK,
70    RTEMS_MONITOR_OBJECT_MPCI,
71    RTEMS_MONITOR_OBJECT_SYMBOL,
72    RTEMS_MONITOR_OBJECT_PTHREAD
73} rtems_monitor_object_type_t;
74
75/*
76 * rtems_monitor_init() flags
77 */
78
79#define RTEMS_MONITOR_SUSPEND   0x0001          /* suspend monitor on startup */
80#define RTEMS_MONITOR_GLOBAL    0x0002          /* monitor should be global */
81#define RTEMS_MONITOR_NOTASK    0x0004 /* do not start monitor task */
82#define RTEMS_MONITOR_NOSYMLOAD 0x0008 /* do not load symbols       */
83#define RTEMS_MONITOR_WAITQUIT  0x0010 /* wait for monitor task to terminate */
84
85/*
86 * Public interfaces for RTEMS data structures monitor is aware of.
87 * These are only used by the monitor.
88 *
89 * NOTE:
90 *  All the canonical objects that correspond to RTEMS managed "objects"
91 *  must have an identical first portion with 'id' and 'name' fields.
92 *
93 *  Others do not have that restriction, even tho we would like them to.
94 *  This is because some of the canonical structures are almost too big
95 *  for shared memory driver (eg: mpci) and we are nickel and diming it.
96 */
97
98/*
99 * Type of a pointer that may be a symbol
100 */
101
102#define MONITOR_SYMBOL_LEN 20
103typedef struct {
104    char       name[MONITOR_SYMBOL_LEN];
105    uint32_t   value;
106    uint32_t   offset;
107} rtems_monitor_symbol_t;
108
109typedef struct {
110    rtems_id            id;
111    rtems_name          name;
112  /* end of common portion */
113} rtems_monitor_generic_t;
114
115/*
116 * Task
117 */
118typedef struct {
119    rtems_id                   id;
120    rtems_name                 name;
121  /* end of common portion */
122    char                       short_name[5];
123    char                       long_name[16];
124    Thread_Entry_information   entry;
125    void                      *stack;
126    uint32_t                   stack_size;
127    char                       scheduler_name[5];
128    rtems_task_priority        priority;
129    States_Control             state;
130    rtems_event_set            events;
131    rtems_mode                 modes;
132    rtems_attribute            attributes;
133    char                       wait[17];
134    uint32_t                   ticks;
135} rtems_monitor_task_t;
136
137/*
138 * Init task
139 */
140
141typedef struct {
142    rtems_id            id;             /* not really an id */
143    rtems_name          name;
144  /* end of common portion */
145    rtems_monitor_symbol_t entry;
146    uint32_t               argument;
147    uint32_t               stack_size;
148    rtems_task_priority    priority;
149    rtems_mode             modes;
150    rtems_attribute        attributes;
151} rtems_monitor_init_task_t;
152
153
154/*
155 * Message queue
156 */
157typedef struct {
158    rtems_id            id;
159    rtems_name          name;
160  /* end of common portion */
161    rtems_attribute     attributes;
162    uint32_t            number_of_pending_messages;
163    uint32_t            maximum_pending_messages;
164    size_t              maximum_message_size;
165} rtems_monitor_queue_t;
166
167/*
168 * Semaphore
169 */
170typedef struct {
171    rtems_id            id;
172    rtems_name          name;
173  /* end of common portion */
174    rtems_attribute     attribute;
175    rtems_task_priority priority_ceiling;
176    uint32_t            max_count;
177    uint32_t            cur_count;
178    rtems_id            holder_id;
179} rtems_monitor_sema_t;
180
181/*
182 * Extension
183 */
184typedef struct {
185    rtems_id                 id;
186    rtems_name               name;
187  /* end of common portion */
188    rtems_monitor_symbol_t  e_create;
189    rtems_monitor_symbol_t  e_start;
190    rtems_monitor_symbol_t  e_restart;
191    rtems_monitor_symbol_t  e_delete;
192    rtems_monitor_symbol_t  e_tswitch;
193    rtems_monitor_symbol_t  e_begin;
194    rtems_monitor_symbol_t  e_exitted;
195    rtems_monitor_symbol_t  e_fatal;
196} rtems_monitor_extension_t;
197
198 /*
199 * Region
200 */
201typedef struct {
202    rtems_id            id;
203    rtems_name          name;
204  /* end of common portion */
205  rtems_attribute     attribute;
206  void *              start_addr;
207  uint32_t            length;
208  uint32_t            page_size;
209  uint32_t            max_seg_size;
210  uint32_t            used_blocks;
211} rtems_monitor_region_t;
212
213/*
214 * Partition
215 */
216typedef struct {
217    rtems_id            id;
218    rtems_name          name;
219  /* end of common portion */
220  rtems_attribute     attribute;
221  const void *        start_addr;
222  uint32_t            length;
223  uint32_t            buf_size;
224  uint32_t            used_blocks;
225} rtems_monitor_part_t;
226
227/*
228 * Device driver
229 */
230
231typedef struct {
232    rtems_id            id;                /* not really an id (should be tho) */
233    rtems_name          name;              /* ditto */
234  /* end of common portion */
235    rtems_monitor_symbol_t initialization; /* initialization procedure */
236    rtems_monitor_symbol_t open;           /* open request procedure */
237    rtems_monitor_symbol_t close;          /* close request procedure */
238    rtems_monitor_symbol_t read;           /* read request procedure */
239    rtems_monitor_symbol_t write;          /* write request procedure */
240    rtems_monitor_symbol_t control;        /* special functions procedure */
241} rtems_monitor_driver_t;
242
243/*
244 * System config
245 */
246
247typedef struct {
248    void               *work_space_start;
249    uint32_t            work_space_size;
250    uint32_t            maximum_tasks;
251    uint32_t            maximum_timers;
252    uint32_t            maximum_semaphores;
253    uint32_t            maximum_message_queues;
254    uint32_t            maximum_partitions;
255    uint32_t            maximum_regions;
256    uint32_t            maximum_ports;
257    uint32_t            maximum_periods;
258    uint32_t            maximum_extensions;
259    uint32_t            microseconds_per_tick;
260    uint32_t            ticks_per_timeslice;
261    uint32_t            number_of_initialization_tasks;
262} rtems_monitor_config_t;
263
264/*
265 * MPCI config
266 */
267
268#if defined(RTEMS_MULTIPROCESSING)
269typedef struct {
270    uint32_t    node;                   /* local node number */
271    uint32_t    maximum_nodes;          /* maximum # nodes in system */
272    uint32_t    maximum_global_objects; /* maximum # global objects */
273    uint32_t    maximum_proxies;        /* maximum # proxies */
274
275    uint32_t                 default_timeout;        /* in ticks */
276    size_t                   maximum_packet_size;
277    rtems_monitor_symbol_t   initialization;
278    rtems_monitor_symbol_t   get_packet;
279    rtems_monitor_symbol_t   return_packet;
280    rtems_monitor_symbol_t   send_packet;
281    rtems_monitor_symbol_t   receive_packet;
282} rtems_monitor_mpci_t;
283#endif
284
285/*
286 * The generic canonical information union
287 */
288
289typedef union {
290    rtems_monitor_generic_t    generic;
291    rtems_monitor_task_t       task;
292    rtems_monitor_queue_t      queue;
293    rtems_monitor_sema_t       sema;
294    rtems_monitor_extension_t  extension;
295    rtems_monitor_driver_t     driver;
296    rtems_monitor_config_t     config;
297    rtems_monitor_region_t     region;
298    rtems_monitor_part_t       part;
299#if defined(RTEMS_MULTIPROCESSING)
300    rtems_monitor_mpci_t       mpci;
301#endif
302    rtems_monitor_init_task_t  itask;
303} rtems_monitor_union_t;
304
305/*
306 * Support for talking to other monitors
307 */
308
309/*
310 * Names of other monitors
311 */
312
313#define RTEMS_MONITOR_NAME        (rtems_build_name('R', 'M', 'O', 'N'))
314#define RTEMS_MONITOR_SERVER_NAME (rtems_build_name('R', 'M', 'S', 'V'))
315#define RTEMS_MONITOR_QUEUE_NAME  (rtems_build_name('R', 'M', 'S', 'Q'))
316#define RTEMS_MONITOR_RESPONSE_QUEUE_NAME (rtems_build_name('R', 'M', 'R', 'Q'))
317
318#define RTEMS_MONITOR_SERVER_RESPONSE    0x0001
319#define RTEMS_MONITOR_SERVER_CANONICAL   0x0002
320
321typedef struct
322{
323    uint32_t    command;
324    rtems_id    return_id;
325    uint32_t    argument0;
326    uint32_t    argument1;
327    uint32_t    argument2;
328    uint32_t    argument3;
329    uint32_t    argument4;
330    uint32_t    argument5;
331} rtems_monitor_server_request_t;
332
333typedef struct
334{
335    uint32_t    command;
336    uint32_t    result0;
337    uint32_t    result1;
338    rtems_monitor_union_t payload;
339} rtems_monitor_server_response_t;
340
341extern rtems_id  rtems_monitor_task_id;
342
343extern uint32_t   rtems_monitor_node;          /* our node number */
344extern uint32_t   rtems_monitor_default_node;  /* current default for commands */
345
346/*
347 * Monitor command function and table entry
348 */
349
350typedef struct rtems_monitor_command_entry_s rtems_monitor_command_entry_t;
351typedef union _rtems_monitor_command_arg_t   rtems_monitor_command_arg_t;
352
353typedef void (*rtems_monitor_command_function_t)(
354  int                                argc,
355  char                             **argv,
356  const rtems_monitor_command_arg_t *command_arg,
357  bool                               verbose
358);
359
360union _rtems_monitor_command_arg_t {
361  rtems_monitor_object_type_t   monitor_object;
362  rtems_status_code             status_code;
363  rtems_symbol_table_t          **symbol_table;
364  const rtems_monitor_command_entry_t *monitor_command_entry;
365};
366
367struct rtems_monitor_command_entry_s {
368    const char *command;      /* command name */
369    const char *usage;        /* usage string for the command */
370    uint32_t arguments_required;    /* # of required args */
371    rtems_monitor_command_function_t command_function;
372                               /* Some argument for the command */
373    rtems_monitor_command_arg_t command_arg;
374    const rtems_monitor_command_entry_t *next;
375};
376
377
378typedef const void *(*rtems_monitor_object_next_fn)(void *, void *, rtems_id *);
379typedef void (*rtems_monitor_object_canonical_fn)(void *, const void *);
380typedef void (*rtems_monitor_object_dump_header_fn)(bool);
381typedef void (*rtems_monitor_object_dump_fn)(void *, bool);
382
383typedef struct {
384    rtems_monitor_object_type_t         type;
385    void                               *object_information;
386    int                                 size;   /* of canonical object */
387    rtems_monitor_object_next_fn        next;
388    rtems_monitor_object_canonical_fn   canonical;
389    rtems_monitor_object_dump_header_fn dump_header;
390    rtems_monitor_object_dump_fn        dump;
391} rtems_monitor_object_info_t;
392
393typedef bool (*rtems_monitor_per_command_routine)(const rtems_monitor_command_entry_t *, void *);
394
395/* monitor.c */
396void    rtems_monitor_pause_cmd(int, char **, const rtems_monitor_command_arg_t*, bool);
397void    rtems_monitor_fatal_cmd(int, char **, const rtems_monitor_command_arg_t*, bool);
398void    rtems_monitor_continue_cmd(int, char **, const rtems_monitor_command_arg_t*, bool);
399void    rtems_monitor_debugger_cmd(int, char **, const rtems_monitor_command_arg_t*, bool);
400void    rtems_monitor_reset_cmd(int, char **, const rtems_monitor_command_arg_t*, bool);
401void    rtems_monitor_node_cmd(int, char **, const rtems_monitor_command_arg_t*, bool);
402void    rtems_monitor_symbols_loadup(void);
403int     rtems_monitor_insert_cmd(rtems_monitor_command_entry_t *);
404void    rtems_monitor_wakeup(void);
405void rtems_monitor_command_iterate(rtems_monitor_per_command_routine routine, void *arg);
406rtems_status_code rtems_monitor_suspend(rtems_interval timeout);
407
408/* editor.c */
409void    rtems_monitor_kill(void);
410void    rtems_monitor_init(uint32_t);
411void    rtems_monitor_task(rtems_task_argument);
412
413/* server.c */
414void    rtems_monitor_server_kill(void);
415rtems_status_code rtems_monitor_server_request(uint32_t  , rtems_monitor_server_request_t *, rtems_monitor_server_response_t *);
416void    rtems_monitor_server_task(rtems_task_argument);
417void    rtems_monitor_server_init(uint32_t);
418
419/* command.c */
420int     rtems_monitor_make_argv(char *, int *, char **);
421int     rtems_monitor_command_read(char *, int *, char **);
422void    rtems_monitor_command_usage(const rtems_monitor_command_entry_t *, const char *);
423void    rtems_monitor_help_cmd(int, char **, const rtems_monitor_command_arg_t *, bool);
424const rtems_monitor_command_entry_t *rtems_monitor_command_lookup(const char *name);
425
426/* prmisc.c */
427void       rtems_monitor_separator(void);
428uint32_t   rtems_monitor_pad(uint32_t   dest_col, uint32_t   curr_col);
429int        rtems_monitor_dump_decimal(uint32_t   num);
430int        rtems_monitor_dump_hex(uint32_t   num);
431int        rtems_monitor_dump_addr(const void *addr);
432int        rtems_monitor_dump_id(rtems_id id);
433int        rtems_monitor_dump_name(rtems_id id);
434int        rtems_monitor_dump_priority(rtems_task_priority priority);
435int        rtems_monitor_dump_state(States_Control state);
436int        rtems_monitor_dump_modes(rtems_mode modes);
437int        rtems_monitor_dump_attributes(rtems_attribute attributes);
438int        rtems_monitor_dump_events(rtems_event_set events);
439
440/* object.c */
441rtems_id   rtems_monitor_id_fixup(rtems_id, uint32_t  , rtems_monitor_object_type_t);
442const rtems_monitor_object_info_t *rtems_monitor_object_lookup(rtems_monitor_object_type_t type);
443rtems_id   rtems_monitor_object_canonical_get(rtems_monitor_object_type_t, rtems_id, void *, size_t *size_p);
444rtems_id   rtems_monitor_object_canonical_next(const rtems_monitor_object_info_t *, rtems_id, void *);
445const void *rtems_monitor_object_next(void *, void *, rtems_id, rtems_id *);
446rtems_id   rtems_monitor_object_canonical(rtems_id, const void *);
447void       rtems_monitor_object_cmd(int, char **, const rtems_monitor_command_arg_t*, bool);
448
449/* manager.c */
450const void *rtems_monitor_manager_next(void *, void *, rtems_id *);
451
452/* config.c */
453void       rtems_monitor_config_canonical(rtems_monitor_config_t *, const void *);
454const void *rtems_monitor_config_next(void *, rtems_monitor_config_t *, rtems_id *);
455void       rtems_monitor_config_dump_header(bool);
456int        rtems_monitor_config_dump(rtems_monitor_config_t *, bool verbose);
457
458/* mpci.c */
459#if defined(RTEMS_MULTIPROCESSING)
460void       rtems_monitor_mpci_canonical(rtems_monitor_mpci_t *, const void *);
461const void *rtems_monitor_mpci_next(void *, rtems_monitor_mpci_t *, rtems_id *);
462void       rtems_monitor_mpci_dump_header(bool);
463void       rtems_monitor_mpci_dump(rtems_monitor_mpci_t *, bool verbose);
464#endif
465
466/* itask.c */
467void       rtems_monitor_init_task_canonical(rtems_monitor_init_task_t *, const void *);
468const void *rtems_monitor_init_task_next(void *, rtems_monitor_init_task_t *, rtems_id *);
469void       rtems_monitor_init_task_dump_header(bool);
470void       rtems_monitor_init_task_dump(rtems_monitor_init_task_t *, bool verbose);
471
472/* extension.c */
473void       rtems_monitor_extension_canonical(rtems_monitor_extension_t *, const void *);
474void       rtems_monitor_extension_dump_header(bool verbose);
475void       rtems_monitor_extension_dump(rtems_monitor_extension_t *, bool);
476
477/* task.c */
478void    rtems_monitor_task_canonical(rtems_monitor_task_t *, const void *);
479void    rtems_monitor_task_dump_header(bool verbose);
480void    rtems_monitor_task_dump(rtems_monitor_task_t *, bool);
481
482/* sema.c */
483void    rtems_monitor_sema_canonical(rtems_monitor_sema_t *, const void *);
484void    rtems_monitor_sema_dump_header(bool verbose);
485void    rtems_monitor_sema_dump(rtems_monitor_sema_t *, bool);
486
487/* queue.c */
488void    rtems_monitor_queue_canonical(rtems_monitor_queue_t *, const void *);
489void    rtems_monitor_queue_dump_header(bool verbose);
490void    rtems_monitor_queue_dump(rtems_monitor_queue_t *, bool);
491
492/* region.c */
493void    rtems_monitor_region_canonical(rtems_monitor_region_t *, const void *);
494void    rtems_monitor_region_dump_header(bool verbose);
495void    rtems_monitor_region_dump(rtems_monitor_region_t *, bool);
496
497/* partition.c */
498void    rtems_monitor_part_canonical(rtems_monitor_part_t *, const void *);
499void    rtems_monitor_part_dump_header(bool verbose);
500void    rtems_monitor_part_dump(rtems_monitor_part_t *, bool);
501
502/* driver.c */
503const void *rtems_monitor_driver_next(void *, rtems_monitor_driver_t *, rtems_id *);
504void     rtems_monitor_driver_canonical(rtems_monitor_driver_t *, const void *);
505void     rtems_monitor_driver_dump_header(bool);
506void     rtems_monitor_driver_dump(rtems_monitor_driver_t *, bool);
507
508/* symbols.c */
509rtems_symbol_table_t *rtems_symbol_table_create(void);
510void                  rtems_symbol_table_destroy(rtems_symbol_table_t *table);
511
512rtems_symbol_t *rtems_symbol_create(rtems_symbol_table_t *, const char *, uint32_t);
513rtems_symbol_t *rtems_symbol_value_lookup(rtems_symbol_table_t *, uint32_t);
514const rtems_symbol_t *rtems_symbol_value_lookup_exact(rtems_symbol_table_t *, uint32_t);
515rtems_symbol_t *rtems_symbol_name_lookup(rtems_symbol_table_t *, const char *);
516const void *rtems_monitor_symbol_next(void *object_info, rtems_monitor_symbol_t *, rtems_id *);
517void    rtems_monitor_symbol_canonical(rtems_monitor_symbol_t *, rtems_symbol_t *);
518void    rtems_monitor_symbol_canonical_by_name(rtems_monitor_symbol_t *, const char *);
519void    rtems_monitor_symbol_canonical_by_value(rtems_monitor_symbol_t *, void *);
520uint32_t   rtems_monitor_symbol_dump(rtems_monitor_symbol_t *, bool);
521void    rtems_monitor_symbol_cmd(int, char **, const rtems_monitor_command_arg_t*, bool);
522
523#if defined(RTEMS_NETWORKING)
524void mon_ifconfig(
525  int argc,
526  char *argv[],
527  uint32_t command_arg,
528  bool verbose
529);
530void mon_route(
531  int argc,
532  char *argv[],
533  uint32_t command_arg,
534  bool verbose
535);
536#endif
537
538/* mon-object.c */
539const rtems_monitor_object_info_t *rtems_monitor_object_lookup(
540  rtems_monitor_object_type_t type
541);
542
543/* shared data */
544extern rtems_symbol_table_t *rtems_monitor_symbols;
545
546#define MONITOR_WAKEUP_EVENT   RTEMS_EVENT_0
547
548#ifdef __cplusplus
549}
550#endif
551
552#endif  /* ! __MONITOR_H */
Note: See TracBrowser for help on using the repository browser.