1 /* GDB parameters implemented in Python
3 Copyright (C) 2008-2020 Free Software Foundation, Inc.
5 This file is part of GDB.
7 This program is free software; you can redistribute it and/or modify
8 it under the terms of the GNU General Public License as published by
9 the Free Software Foundation; either version 3 of the License, or
10 (at your option) any later version.
12 This program is distributed in the hope that it will be useful,
13 but WITHOUT ANY WARRANTY; without even the implied warranty of
14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 GNU General Public License for more details.
17 You should have received a copy of the GNU General Public License
18 along with this program. If not, see <http://www.gnu.org/licenses/>. */
23 #include "python-internal.h"
26 #include "cli/cli-decode.h"
27 #include "completer.h"
29 #include "arch-utils.h"
31 /* Parameter constants and their values. */
38 struct parm_constant parm_constants
[] =
40 { "PARAM_BOOLEAN", var_boolean
}, /* ARI: var_boolean */
41 { "PARAM_AUTO_BOOLEAN", var_auto_boolean
},
42 { "PARAM_UINTEGER", var_uinteger
},
43 { "PARAM_INTEGER", var_integer
},
44 { "PARAM_STRING", var_string
},
45 { "PARAM_STRING_NOESCAPE", var_string_noescape
},
46 { "PARAM_OPTIONAL_FILENAME", var_optional_filename
},
47 { "PARAM_FILENAME", var_filename
},
48 { "PARAM_ZINTEGER", var_zinteger
},
49 { "PARAM_ZUINTEGER", var_zuinteger
},
50 { "PARAM_ZUINTEGER_UNLIMITED", var_zuinteger_unlimited
},
51 { "PARAM_ENUM", var_enum
},
55 /* A union that can hold anything described by enum var_types. */
58 /* Hold a boolean value. */
61 /* Hold an integer value. */
64 /* Hold an auto_boolean. */
65 enum auto_boolean autoboolval
;
67 /* Hold an unsigned integer value, for uinteger. */
70 /* Hold a string, for the various string types. */
73 /* Hold a string, for enums. */
74 const char *cstringval
;
77 /* A GDB parameter. */
82 /* The type of the parameter. */
85 /* The value of the parameter. */
86 union parmpy_variable value
;
88 /* For an enum command, the possible values. The vector is
89 allocated with xmalloc, as is each element. It is
91 const char **enumeration
;
94 typedef struct parmpy_object parmpy_object
;
96 extern PyTypeObject parmpy_object_type
97 CPYCHECKER_TYPE_OBJECT_FOR_TYPEDEF ("parmpy_object");
99 /* Some handy string constants. */
100 static PyObject
*set_doc_cst
;
101 static PyObject
*show_doc_cst
;
105 /* Get an attribute. */
107 get_attr (PyObject
*obj
, PyObject
*attr_name
)
109 if (PyString_Check (attr_name
)
111 && ! PyUnicode_CompareWithASCIIString (attr_name
, "value"))
113 && ! strcmp (PyString_AsString (attr_name
), "value"))
116 parmpy_object
*self
= (parmpy_object
*) obj
;
118 return gdbpy_parameter_value (self
->type
, &self
->value
);
121 return PyObject_GenericGetAttr (obj
, attr_name
);
124 /* Set a parameter value from a Python value. Return 0 on success. Returns
125 -1 on error, with a python exception set. */
127 set_parameter_value (parmpy_object
*self
, PyObject
*value
)
134 case var_string_noescape
:
135 case var_optional_filename
:
137 if (! gdbpy_is_string (value
)
138 && (self
->type
== var_filename
139 || value
!= Py_None
))
141 PyErr_SetString (PyExc_RuntimeError
,
142 _("String required for filename."));
146 if (value
== Py_None
)
148 xfree (self
->value
.stringval
);
149 if (self
->type
== var_optional_filename
)
150 self
->value
.stringval
= xstrdup ("");
152 self
->value
.stringval
= NULL
;
156 gdb::unique_xmalloc_ptr
<char>
157 string (python_string_to_host_string (value
));
161 xfree (self
->value
.stringval
);
162 self
->value
.stringval
= string
.release ();
170 if (! gdbpy_is_string (value
))
172 PyErr_SetString (PyExc_RuntimeError
,
173 _("ENUM arguments must be a string."));
177 gdb::unique_xmalloc_ptr
<char>
178 str (python_string_to_host_string (value
));
181 for (i
= 0; self
->enumeration
[i
]; ++i
)
182 if (! strcmp (self
->enumeration
[i
], str
.get ()))
184 if (! self
->enumeration
[i
])
186 PyErr_SetString (PyExc_RuntimeError
,
187 _("The value must be member of an enumeration."));
190 self
->value
.cstringval
= self
->enumeration
[i
];
195 if (! PyBool_Check (value
))
197 PyErr_SetString (PyExc_RuntimeError
,
198 _("A boolean argument is required."));
201 cmp
= PyObject_IsTrue (value
);
204 self
->value
.boolval
= cmp
;
207 case var_auto_boolean
:
208 if (! PyBool_Check (value
) && value
!= Py_None
)
210 PyErr_SetString (PyExc_RuntimeError
,
211 _("A boolean or None is required"));
215 if (value
== Py_None
)
216 self
->value
.autoboolval
= AUTO_BOOLEAN_AUTO
;
219 cmp
= PyObject_IsTrue (value
);
223 self
->value
.autoboolval
= AUTO_BOOLEAN_TRUE
;
225 self
->value
.autoboolval
= AUTO_BOOLEAN_FALSE
;
233 case var_zuinteger_unlimited
:
238 if (! PyInt_Check (value
))
240 PyErr_SetString (PyExc_RuntimeError
,
241 _("The value must be integer."));
245 if (! gdb_py_int_as_long (value
, &l
))
255 ok
= (l
>= 0 && l
<= UINT_MAX
);
258 case var_zuinteger_unlimited
:
259 ok
= (l
>= -1 && l
<= INT_MAX
);
263 ok
= (l
>= INT_MIN
&& l
<= INT_MAX
);
269 ok
= (l
>= INT_MIN
&& l
<= INT_MAX
);
273 gdb_assert_not_reached ("unknown var_ constant");
278 PyErr_SetString (PyExc_RuntimeError
,
279 _("Range exceeded."));
283 if (self
->type
== var_uinteger
|| self
->type
== var_zuinteger
)
284 self
->value
.uintval
= (unsigned) l
;
286 self
->value
.intval
= (int) l
;
291 PyErr_SetString (PyExc_RuntimeError
,
292 _("Unhandled type in parameter value."));
299 /* Set an attribute. Returns -1 on error, with a python exception set. */
301 set_attr (PyObject
*obj
, PyObject
*attr_name
, PyObject
*val
)
303 if (PyString_Check (attr_name
)
305 && ! PyUnicode_CompareWithASCIIString (attr_name
, "value"))
307 && ! strcmp (PyString_AsString (attr_name
), "value"))
312 PyErr_SetString (PyExc_RuntimeError
,
313 _("Cannot delete a parameter's value."));
316 return set_parameter_value ((parmpy_object
*) obj
, val
);
319 return PyObject_GenericSetAttr (obj
, attr_name
, val
);
322 /* A helper function which returns a documentation string for an
325 static gdb::unique_xmalloc_ptr
<char>
326 get_doc_string (PyObject
*object
, PyObject
*attr
)
328 gdb::unique_xmalloc_ptr
<char> result
;
330 if (PyObject_HasAttr (object
, attr
))
332 gdbpy_ref
<> ds_obj (PyObject_GetAttr (object
, attr
));
334 if (ds_obj
!= NULL
&& gdbpy_is_string (ds_obj
.get ()))
336 result
= python_string_to_host_string (ds_obj
.get ());
338 gdbpy_print_stack ();
342 result
.reset (xstrdup (_("This command is not documented.")));
346 /* Helper function which will execute a METHOD in OBJ passing the
347 argument ARG. ARG can be NULL. METHOD should return a Python
348 string. If this function returns NULL, there has been an error and
349 the appropriate exception set. */
350 static gdb::unique_xmalloc_ptr
<char>
351 call_doc_function (PyObject
*obj
, PyObject
*method
, PyObject
*arg
)
353 gdb::unique_xmalloc_ptr
<char> data
;
354 gdbpy_ref
<> result (PyObject_CallMethodObjArgs (obj
, method
, arg
, NULL
));
359 if (gdbpy_is_string (result
.get ()))
361 data
= python_string_to_host_string (result
.get ());
367 PyErr_SetString (PyExc_RuntimeError
,
368 _("Parameter must return a string value."));
375 /* A callback function that is registered against the respective
376 add_setshow_* set_doc prototype. This function will either call
377 the Python function "get_set_string" or extract the Python
378 attribute "set_doc" and return the contents as a string. If
379 neither exist, insert a string indicating the Parameter is not
382 get_set_value (const char *args
, int from_tty
,
383 struct cmd_list_element
*c
)
385 PyObject
*obj
= (PyObject
*) get_cmd_context (c
);
386 gdb::unique_xmalloc_ptr
<char> set_doc_string
;
388 gdbpy_enter
enter_py (get_current_arch (), current_language
);
389 gdbpy_ref
<> set_doc_func (PyString_FromString ("get_set_string"));
391 if (set_doc_func
== NULL
)
393 gdbpy_print_stack ();
397 if (PyObject_HasAttr (obj
, set_doc_func
.get ()))
399 set_doc_string
= call_doc_function (obj
, set_doc_func
.get (), NULL
);
400 if (! set_doc_string
)
401 gdbpy_handle_exception ();
404 const char *str
= set_doc_string
.get ();
405 if (str
!= nullptr && str
[0] != '\0')
406 fprintf_filtered (gdb_stdout
, "%s\n", str
);
409 /* A callback function that is registered against the respective
410 add_setshow_* show_doc prototype. This function will either call
411 the Python function "get_show_string" or extract the Python
412 attribute "show_doc" and return the contents as a string. If
413 neither exist, insert a string indicating the Parameter is not
416 get_show_value (struct ui_file
*file
, int from_tty
,
417 struct cmd_list_element
*c
,
420 PyObject
*obj
= (PyObject
*) get_cmd_context (c
);
421 gdb::unique_xmalloc_ptr
<char> show_doc_string
;
423 gdbpy_enter
enter_py (get_current_arch (), current_language
);
424 gdbpy_ref
<> show_doc_func (PyString_FromString ("get_show_string"));
426 if (show_doc_func
== NULL
)
428 gdbpy_print_stack ();
432 if (PyObject_HasAttr (obj
, show_doc_func
.get ()))
434 gdbpy_ref
<> val_obj (PyString_FromString (value
));
438 gdbpy_print_stack ();
442 show_doc_string
= call_doc_function (obj
, show_doc_func
.get (),
444 if (! show_doc_string
)
446 gdbpy_print_stack ();
450 fprintf_filtered (file
, "%s\n", show_doc_string
.get ());
454 /* We have to preserve the existing < GDB 7.3 API. If a
455 callback function does not exist, then attempt to read the
456 show_doc attribute. */
457 show_doc_string
= get_doc_string (obj
, show_doc_cst
);
458 fprintf_filtered (file
, "%s %s\n", show_doc_string
.get (), value
);
463 /* A helper function that dispatches to the appropriate add_setshow
466 add_setshow_generic (int parmclass
, enum command_class cmdclass
,
467 const char *cmd_name
, parmpy_object
*self
,
468 const char *set_doc
, const char *show_doc
,
469 const char *help_doc
,
470 struct cmd_list_element
**set_list
,
471 struct cmd_list_element
**show_list
)
473 struct cmd_list_element
*param
= NULL
;
474 const char *tmp_name
= NULL
;
480 add_setshow_boolean_cmd (cmd_name
, cmdclass
,
481 &self
->value
.boolval
, set_doc
, show_doc
,
482 help_doc
, get_set_value
, get_show_value
,
483 set_list
, show_list
);
487 case var_auto_boolean
:
488 add_setshow_auto_boolean_cmd (cmd_name
, cmdclass
,
489 &self
->value
.autoboolval
,
490 set_doc
, show_doc
, help_doc
,
491 get_set_value
, get_show_value
,
492 set_list
, show_list
);
496 add_setshow_uinteger_cmd (cmd_name
, cmdclass
,
497 &self
->value
.uintval
, set_doc
, show_doc
,
498 help_doc
, get_set_value
, get_show_value
,
499 set_list
, show_list
);
503 add_setshow_integer_cmd (cmd_name
, cmdclass
,
504 &self
->value
.intval
, set_doc
, show_doc
,
505 help_doc
, get_set_value
, get_show_value
,
506 set_list
, show_list
); break;
509 add_setshow_string_cmd (cmd_name
, cmdclass
,
510 &self
->value
.stringval
, set_doc
, show_doc
,
511 help_doc
, get_set_value
, get_show_value
,
512 set_list
, show_list
); break;
514 case var_string_noescape
:
515 add_setshow_string_noescape_cmd (cmd_name
, cmdclass
,
516 &self
->value
.stringval
,
517 set_doc
, show_doc
, help_doc
,
518 get_set_value
, get_show_value
,
519 set_list
, show_list
);
523 case var_optional_filename
:
524 add_setshow_optional_filename_cmd (cmd_name
, cmdclass
,
525 &self
->value
.stringval
, set_doc
,
526 show_doc
, help_doc
, get_set_value
,
527 get_show_value
, set_list
,
532 add_setshow_filename_cmd (cmd_name
, cmdclass
,
533 &self
->value
.stringval
, set_doc
, show_doc
,
534 help_doc
, get_set_value
, get_show_value
,
535 set_list
, show_list
); break;
538 add_setshow_zinteger_cmd (cmd_name
, cmdclass
,
539 &self
->value
.intval
, set_doc
, show_doc
,
540 help_doc
, get_set_value
, get_show_value
,
541 set_list
, show_list
);
545 add_setshow_zuinteger_cmd (cmd_name
, cmdclass
,
546 &self
->value
.uintval
, set_doc
, show_doc
,
547 help_doc
, get_set_value
, get_show_value
,
548 set_list
, show_list
);
551 case var_zuinteger_unlimited
:
552 add_setshow_zuinteger_unlimited_cmd (cmd_name
, cmdclass
,
553 &self
->value
.intval
, set_doc
,
554 show_doc
, help_doc
, get_set_value
,
556 set_list
, show_list
);
560 add_setshow_enum_cmd (cmd_name
, cmdclass
, self
->enumeration
,
561 &self
->value
.cstringval
, set_doc
, show_doc
,
562 help_doc
, get_set_value
, get_show_value
,
563 set_list
, show_list
);
564 /* Initialize the value, just in case. */
565 self
->value
.cstringval
= self
->enumeration
[0];
569 /* Lookup created parameter, and register Python object against the
570 parameter context. Perform this task against both lists. */
572 param
= lookup_cmd (&tmp_name
, *show_list
, "", 0, 1);
574 set_cmd_context (param
, self
);
577 param
= lookup_cmd (&tmp_name
, *set_list
, "", 0, 1);
579 set_cmd_context (param
, self
);
582 /* A helper which computes enum values. Returns 1 on success. Returns 0 on
583 error, with a python exception set. */
585 compute_enum_values (parmpy_object
*self
, PyObject
*enum_values
)
591 PyErr_SetString (PyExc_RuntimeError
,
592 _("An enumeration is required for PARAM_ENUM."));
596 if (! PySequence_Check (enum_values
))
598 PyErr_SetString (PyExc_RuntimeError
,
599 _("The enumeration is not a sequence."));
603 size
= PySequence_Size (enum_values
);
608 PyErr_SetString (PyExc_RuntimeError
,
609 _("The enumeration is empty."));
613 gdb_argv
holder (XCNEWVEC (char *, size
+ 1));
614 char **enumeration
= holder
.get ();
616 for (i
= 0; i
< size
; ++i
)
618 gdbpy_ref
<> item (PySequence_GetItem (enum_values
, i
));
622 if (! gdbpy_is_string (item
.get ()))
624 PyErr_SetString (PyExc_RuntimeError
,
625 _("The enumeration item not a string."));
628 enumeration
[i
] = python_string_to_host_string (item
.get ()).release ();
629 if (enumeration
[i
] == NULL
)
633 self
->enumeration
= const_cast<const char**> (holder
.release ());
637 /* Object initializer; sets up gdb-side structures for command.
639 Use: __init__(NAME, CMDCLASS, PARMCLASS, [ENUM])
641 NAME is the name of the parameter. It may consist of multiple
642 words, in which case the final word is the name of the new command,
643 and earlier words must be prefix commands.
645 CMDCLASS is the kind of command. It should be one of the COMMAND_*
646 constants defined in the gdb module.
648 PARMCLASS is the type of the parameter. It should be one of the
649 PARAM_* constants defined in the gdb module.
651 If PARMCLASS is PARAM_ENUM, then the final argument should be a
652 collection of strings. These strings are the valid values for this
655 The documentation for the parameter is taken from the doc string
656 for the python class.
658 Returns -1 on error, with a python exception set. */
661 parmpy_init (PyObject
*self
, PyObject
*args
, PyObject
*kwds
)
663 parmpy_object
*obj
= (parmpy_object
*) self
;
665 gdb::unique_xmalloc_ptr
<char> set_doc
, show_doc
, doc
;
667 int parmclass
, cmdtype
;
668 PyObject
*enum_values
= NULL
;
669 struct cmd_list_element
**set_list
, **show_list
;
671 if (! PyArg_ParseTuple (args
, "sii|O", &name
, &cmdtype
, &parmclass
,
675 if (cmdtype
!= no_class
&& cmdtype
!= class_run
676 && cmdtype
!= class_vars
&& cmdtype
!= class_stack
677 && cmdtype
!= class_files
&& cmdtype
!= class_support
678 && cmdtype
!= class_info
&& cmdtype
!= class_breakpoint
679 && cmdtype
!= class_trace
&& cmdtype
!= class_obscure
680 && cmdtype
!= class_maintenance
)
682 PyErr_Format (PyExc_RuntimeError
, _("Invalid command class argument."));
686 if (parmclass
!= var_boolean
/* ARI: var_boolean */
687 && parmclass
!= var_auto_boolean
688 && parmclass
!= var_uinteger
&& parmclass
!= var_integer
689 && parmclass
!= var_string
&& parmclass
!= var_string_noescape
690 && parmclass
!= var_optional_filename
&& parmclass
!= var_filename
691 && parmclass
!= var_zinteger
&& parmclass
!= var_zuinteger
692 && parmclass
!= var_zuinteger_unlimited
&& parmclass
!= var_enum
)
694 PyErr_SetString (PyExc_RuntimeError
,
695 _("Invalid parameter class argument."));
699 if (enum_values
&& parmclass
!= var_enum
)
701 PyErr_SetString (PyExc_RuntimeError
,
702 _("Only PARAM_ENUM accepts a fourth argument."));
705 if (parmclass
== var_enum
)
707 if (! compute_enum_values (obj
, enum_values
))
711 obj
->enumeration
= NULL
;
712 obj
->type
= (enum var_types
) parmclass
;
713 memset (&obj
->value
, 0, sizeof (obj
->value
));
715 cmd_name
= gdbpy_parse_command_name (name
, &set_list
,
721 cmd_name
= gdbpy_parse_command_name (name
, &show_list
,
726 set_doc
= get_doc_string (self
, set_doc_cst
);
727 show_doc
= get_doc_string (self
, show_doc_cst
);
728 doc
= get_doc_string (self
, gdbpy_doc_cst
);
734 add_setshow_generic (parmclass
, (enum command_class
) cmdtype
,
736 set_doc
.get (), show_doc
.get (),
737 doc
.get (), set_list
, show_list
);
739 catch (const gdb_exception
&except
)
743 gdbpy_convert_exception (except
);
752 /* Initialize the 'parameters' module. */
754 gdbpy_initialize_parameters (void)
758 parmpy_object_type
.tp_new
= PyType_GenericNew
;
759 if (PyType_Ready (&parmpy_object_type
) < 0)
762 set_doc_cst
= PyString_FromString ("set_doc");
765 show_doc_cst
= PyString_FromString ("show_doc");
769 for (i
= 0; parm_constants
[i
].name
; ++i
)
771 if (PyModule_AddIntConstant (gdb_module
,
772 parm_constants
[i
].name
,
773 parm_constants
[i
].value
) < 0)
777 return gdb_pymodule_addobject (gdb_module
, "Parameter",
778 (PyObject
*) &parmpy_object_type
);
783 PyTypeObject parmpy_object_type
=
785 PyVarObject_HEAD_INIT (NULL
, 0)
786 "gdb.Parameter", /*tp_name*/
787 sizeof (parmpy_object
), /*tp_basicsize*/
796 0, /*tp_as_sequence*/
801 get_attr
, /*tp_getattro*/
802 set_attr
, /*tp_setattro*/
804 Py_TPFLAGS_DEFAULT
| Py_TPFLAGS_BASETYPE
, /*tp_flags*/
805 "GDB parameter object", /* tp_doc */
808 0, /* tp_richcompare */
809 0, /* tp_weaklistoffset */
817 0, /* tp_descr_get */
818 0, /* tp_descr_set */
819 0, /* tp_dictoffset */
820 parmpy_init
, /* tp_init */