Project

General

Profile

Plugins Python API » History » Version 20

Alexis Jeandet, 21/09/2015 07:08 PM

1 1 Alexis Jeandet
h1. Plugins Python API
2
3
All SocExplorer plugins expose some common functions and their own functions to the embedded Python terminal.
4
5
h2. Common Functions
6
7 17 Alexis Jeandet
All this functions are either implemented in the base class *socexplorerplugin* or in the plugin itself. They are described with their C++ interface since they are dynamically wrapped in the Python context. To have a better understanding of how the arguments are converted between Python and C++ you can have a look "here":http://pythonqt.sourceforge.net/Developer.html. You can call any of the following methods from any plugin instance; *MyPluginInstance.Method(...)*.
8 1 Alexis Jeandet
9
Function list:
10 2 Alexis Jeandet
* %{color:green}QVariantList% *[[Plugins_Python_API#Read|Read]]* (%{color:green}unsigned int% address, %{color:green}unsigned int% count);
11
* %{color:blue}void% *[[Plugins_Python_API#Write|Write]]* (%{color:green}unsigned int% address, %{color:green}QList<QVariant>% dataList);
12
* %{color:blue}void% *[[Plugins_Python_API#closeMe|closeMe]]* ();
13
* %{color:blue}void% *[[Plugins_Python_API#activate|activate]]* (%{color:green}bool% flag);
14
* %{color:blue}void% *[[Plugins_Python_API#setInstanceName|setInstanceName]]* (%{color:green}const QString% & newName);
15
* %{color:green}bool%  *[[Plugins_Python_API#dumpMemory|dumpMemory]]*  (%{color:green}unsigned int% address, %{color:green}unsigned int% count, %{color:green}QString% file);
16 18 Alexis Jeandet
* %{color:green}bool%  *[[Plugins_Python_API#dumpMemory2|dumpMemory]]*  (%{color:green}unsigned int% address, %{color:green}unsigned int% count, %{color:green}QString% file, %{color:green}const QString% & format);
17 2 Alexis Jeandet
* %{color:green}bool%  *[[Plugins_Python_API#memSet|memSet]]* (%{color:green}unsigned int% address, %{color:green}int% value, %{color:green}unsigned int% count);
18
* %{color:green}bool%  *[[Plugins_Python_API#loadbin|loadbin]]*  (%{color:green}unsigned int% address, %{color:green}QString% file);
19 1 Alexis Jeandet
* %{color:green}bool%  *[[Plugins_Python_API#loadfile|loadfile]]*  (%{color:green}abstractBinFile% * file);
20 15 Alexis Jeandet
21 1 Alexis Jeandet
22 5 Alexis Jeandet
----
23
24
----
25
26 2 Alexis Jeandet
h2(#Read). %{color:green}QVariantList% *Read* (%{color:green}unsigned int% address, %{color:green}unsigned int% count) 
27 1 Alexis Jeandet
28 4 Alexis Jeandet
Reads target memory at given address and return its content. On any root plugin it will read system memory and by default on child plugin it will forward request to parent plugin util it reach root plugin and read system bus. 
29 1 Alexis Jeandet
Note that this function could be re-implemented on a child plugin and have a different behavior.
30 4 Alexis Jeandet
31
The returned list is a *Word* list which means that the smallest data you can read is a word(32 bits) and *count* is the number of words to read. The function respect host endianness so it will convert data depending on target endianness.
32
33 7 Alexis Jeandet
*See also*  %{color:blue}void% *[[Plugins_Python_API#Write|Write]]* (%{color:green}unsigned int% address, %{color:green}QList<QVariant>% dataList);
34 3 Alexis Jeandet
35 9 Alexis Jeandet
----
36
37 2 Alexis Jeandet
h2(#Write). %{color:blue}void% *Write* (%{color:green}unsigned int% address, %{color:green}QList<QVariant>% dataList)
38
39 8 Alexis Jeandet
Writes given *datalist* at given *address* in target system bus. On any root plugin it will writes system memory and by default on child plugin it will forward request to parent plugin util it reach root plugin and writes system bus. 
40
Note that this function could be re-implemented on a child plugin and have a different behavior.
41
The given list is a Word list which means that the smallest data you can write is a word(32 bits). The function respect host endianness so it will convert data depending on target endianness.
42
43 16 Alexis Jeandet
*Example:*
44 10 Alexis Jeandet
45
Let's consider we have a Leon3 with some RAM at 0x40000000 and we want to write 1 2 3 and 0xffffffff. We are connected to the target through *rootplugin* which can be replaced by the plugin are using.
46
47
<pre><code class="python">
48
  rootplugin.Write(0x40000000,[1,2,3,0xffffffff])
49
</code></pre>
50
51 18 Alexis Jeandet
*See also* %{color:green}QVariantList% *[[Plugins_Python_API#Read|Read]]* (%{color:green}unsigned int% address, %{color:green}unsigned int% count);
52 8 Alexis Jeandet
53 9 Alexis Jeandet
----
54
55 2 Alexis Jeandet
h2(#closeMe). %{color:blue}void% *closeMe* ()
56
57 11 Alexis Jeandet
Closes the plugin.
58
59 9 Alexis Jeandet
----
60
61 2 Alexis Jeandet
h2(#activate). %{color:blue}void% *activate* (%{color:green}bool% flag)
62
63 13 Alexis Jeandet
Activates the plugin GUI, this function is called by *SocExplorer* you may not call this function unless you know exactly what you do. By default if the plugin GUI is disabled, it means that the root plugin isn't connected to the target and that any operation on child plugin are forbidden.
64 12 Alexis Jeandet
65 9 Alexis Jeandet
----
66
67 2 Alexis Jeandet
h2(#setInstanceName). %{color:blue}void% *setInstanceName* (%{color:green}const QString% & newName)
68
69 14 Alexis Jeandet
This method will be removed from python context since it may not be used from python terminal.
70
71 9 Alexis Jeandet
----
72
73 2 Alexis Jeandet
h2(#dumpMemory). %{color:green}bool%  *dumpMemory*  (%{color:green}unsigned int% address, %{color:green}unsigned int% count, %{color:green}QString% file)
74 1 Alexis Jeandet
75 16 Alexis Jeandet
Dumps the memory content at given *address* in given *file*. As for *[[Plugins_Python_API#Read|Read]]* method it will read memory word by word and it will handle host and target endianness. The data will be written in ascii with the following format:
76
77
0x40000000: 0xad4c0136
78
0x40000004: 0x665b89c0
79
0x40000008: 0xabc04748
80
0x4000000c: 0x8e110724
81
82
Where left column is address and right column is the corresponding data word. 
83
84
*Example:*
85
86 19 Alexis Jeandet
One interesting usage of this method is to dump memory space while your system is running to see if some memory space got modified. In this example we will load an elf file containing an executable to a Leon3 target through the AHBUARTplugin and dump the first 16 bytes before and after execution and compare them. We also assume that the device is attached to *ttyUSB0*.
87 16 Alexis Jeandet
88
<pre><code class="python">
89 20 Alexis Jeandet
proxy.loadSysDriver("AHBUARTplugin","AHBUARTplugin0")
90
proxy.loadSysDriverToParent("dsu3plugin","dsu3plugin0",AHBUARTplugin0) 
91
AHBUARTplugin0.open("/dev/ttyUSB0",3000000)
92
dsu3plugin0.openFile("/somePath/someElfFile")
93
dsu3plugin0.flashTarget()
94
AHBUARTplugin0.dumpMemory(0x40000000,16,"/somePath/First_dump.txt")
95
dsu3plugin0.run()
96
waitSomeTime()  # You can wait or process something or do whatever you want 
97
AHBUARTplugin0.dumpMemory(0x40000000,16,"/somePath/Second_dump.txt")
98 16 Alexis Jeandet
</code></pre>
99
100
Then you can for example diff your two files:
101
102
<pre><code class="bash">
103 1 Alexis Jeandet
  diff -u /somePath/First_dump.txt /somePath/Second_dump.txt
104
</code></pre>
105 16 Alexis Jeandet
106 18 Alexis Jeandet
*See also*  %{color:green}bool%  *[[Plugins_Python_API#dumpMemory|dumpMemory]]*  (%{color:green}unsigned int% address, %{color:green}unsigned int% count, %{color:green}QString% file, %{color:green}const QString% & format);
107
108 1 Alexis Jeandet
----
109
110 18 Alexis Jeandet
h2(#dumpMemory2). %{color:green}bool%  *dumpMemory*  (%{color:green}unsigned int% address, %{color:green}unsigned int% count, %{color:green}QString% file, %{color:green}const QString% & format)
111 1 Alexis Jeandet
112 18 Alexis Jeandet
This function behaves like  %{color:green}bool%  *[[Plugins_Python_API#dumpMemory|dumpMemory]]*  (%{color:green}unsigned int% address, %{color:green}unsigned int% count, %{color:green}QString% file) except that it allows you to set output file format. Possible format are "srec", "bin" and "hexa".
113
114
*See also*   %{color:green}bool%  *[[Plugins_Python_API#dumpMemory2|dumpMemory]]*  (%{color:green}unsigned int% address, %{color:green}unsigned int% count, %{color:green}QString% file, %{color:green}const QString% & format);
115
116 1 Alexis Jeandet
----
117
118
h2(#memSet). %{color:green}bool%  *memSet* (%{color:green}unsigned int% address, %{color:green}int% value, %{color:green}unsigned int% count)
119 18 Alexis Jeandet
120
Sets memory space with given *value* at given *address*, as for *[[Plugins_Python_API#Write|Write]]* method it will write memory word by word and it will handle host and target endianness.
121
122
*Example:*
123
124
In this example we will first clear memory from 0x40000000 to 0x4000000C and then we will write 0x1234 from 0x40000010 to 0x4000002C
125
126
<pre><code class="python">
127
  proxy.loadSysDriver("AHBUARTplugin","AHBUARTplugin0")
128
  AHBUARTplugin0.open("/dev/ttyUSB0",3000000)
129
  AHBUARTplugin0.memSet(0x40000000,0,4)
130
  AHBUARTplugin0.memSet(0x40000010,0x1234,8)
131
</code></pre>
132 9 Alexis Jeandet
133
----
134 1 Alexis Jeandet
135 16 Alexis Jeandet
h2(#loadbin). %{color:green}bool%  *loadbin*  (%{color:green}unsigned int% address, %{color:green}QString% file)
136 2 Alexis Jeandet
137 9 Alexis Jeandet
----
138
139 16 Alexis Jeandet
h2(#loadfile). %{color:green}bool%  *loadfile*  (%{color:green}abstractBinFile% * file)
140 9 Alexis Jeandet
141
----