File: api_extension.html.in

package info (click to toggle)
libvirt 5.6.0-2
  • links: PTS, VCS
  • area: main
  • in suites: bullseye
  • size: 240,844 kB
  • sloc: ansic: 584,521; xml: 176,725; sh: 9,912; python: 4,731; perl: 4,343; makefile: 3,321; ml: 465
file content (371 lines) | stat: -rw-r--r-- 14,641 bytes parent folder | download | duplicates (2)
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
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
  <body>
    <h1>Implementing a new API in Libvirt</h1>

    <ul id="toc"></ul>

    <p>
      This document walks you through the process of implementing a new
      API in libvirt.  Remember that new API consists of any new public
      functions, as well as the addition of flags or extensions of XML used by
      existing functions.
    </p>

    <p>
      Before you begin coding, it is critical that you propose your
      changes on the libvirt mailing list and get feedback on your ideas to
      make sure what you're proposing fits with the general direction of the
      project.  Even before doing a proof of concept implementation, send an
      email giving an overview of the functionality you think should be
      added to libvirt.  Someone may already be working on the feature you
      want.  Also, recognize that everything you write is likely to undergo
      significant rework as you discuss it with the other developers, so
      don't wait too long before getting feedback.
    </p>

    <p>
      Adding a new API to libvirt is not difficult, but there are quite a
      few steps.  This document assumes that you are familiar with C
      programming and have checked out the libvirt code from the source code
      repository and successfully built the existing tree.  Instructions on
      how to check out and build the code can be found at:
    </p>

    <p>
      <a href="https://libvirt.org/downloads.html">https://libvirt.org/downloads.html</a>
    </p>

    <p>
      Once you have a working development environment, the steps to create a
      new API are:
    </p>
    <ol>
      <li>define the public API</li>
      <li>define the internal driver API</li>
      <li>implement the public API</li>
      <li>implement the remote protocol:
        <ol>
          <li>define the wire protocol format</li>
          <li>implement the RPC client</li>
          <li>implement the server side dispatcher</li>
        </ol>
      </li>
      <li>use new API where appropriate in drivers</li>
      <li>add virsh support</li>
      <li>add common handling for new API</li>
      <li>for each driver that can support the new API:
        <ol>
          <li>add prerequisite support</li>
          <li>fully implement new API</li>
        </ol>
      </li>
    </ol>

    <p>
      It is, of course, possible to implement the pieces in any order, but
      if the development tasks are completed in the order listed, the code
      will compile after each step.  Given the number of changes required,
      verification after each step is highly recommended.
    </p>

    <p>
      Submit new code in the form of one patch per step.  That's not to say
      submit patches before you have working functionality--get the whole thing
      working and make sure you're happy with it.  Then use git to break the
      changes into pieces so you don't drop a big blob of code on the
      mailing list in one go.  Also, you should follow the upstream tree, and
      rebase your series to adapt your patches to work with any other changes
      that were accepted upstream during your development.
    </p>

    <p>
      Don't mix anything else into the patches you submit.  The patches
      should be the minimal changes required to implement the functionality
      you're adding.  If you notice a bug in unrelated code (i.e., code you
      don't have to touch to implement your API change) during development,
      create a patch that just addresses that bug and submit it
      separately.
    </p>

    <h2><a name='publicapi'>Defining the public API</a></h2>

    <p>The first task is to define the public API.  If the new API
      involves an XML extension, you have to enhance the RelaxNG
      schema and document the new elements or attributes:</p>

    <p><code>
        docs/schemas/domaincommon.rng<br/>
        docs/formatdomain.html.in
    </code></p>

    <p>If the API extension involves a new function, you have to add a
      declaration in the public header, and arrange to export the
      function name (symbol) so other programs can link against the
      libvirt library and call the new function:</p>

    <p><code>
        include/libvirt/libvirt-$MODULE.h.in
        src/libvirt_public.syms
    </code></p>

    <p>
      This task is in many ways the most important to get right, since once
      the API has been committed to the repository, it's libvirt's policy
      never to change it.  Mistakes in the implementation are bugs that you
      can fix.  Make a mistake in the API definition and you're stuck with
      it, so think carefully about the interface and don't be afraid to
      rework it as you go through the process of implementing it.
    </p>

    <h2><a name='internalapi'>Defining the internal API</a></h2>

    <p>
      Each public API call is associated with a driver, such as a host
      virtualization driver, a network virtualization driver, a storage
      virtualization driver, a state driver, or a device monitor.  Adding
      the internal API is ordinarily a matter of adding a new member to the
      struct representing one of these drivers.
    </p>

    <p>
      Of course, it's possible that the new API will involve the creation of
      an entirely new driver type, in which case the changes will include the
      creation of a new struct type to represent the new driver type.
    </p>

    <p>The driver structs are defined in:</p>

    <p><code>src/driver-$MODULE.h</code></p>

    <p>
      To define the internal API, first typedef the driver function
      prototype and then add a new field for it to the relevant driver
      struct.  Then, update all existing instances of the driver to
      provide a <code>NULL</code> stub for the new function.
    </p>

    <h2><a name='implpublic'>Implementing the public API</a></h2>

    <p>
      Implementing the public API is largely a formality in which we wire up
      public API to the internal driver API.  The public API implementation
      takes care of some basic validity checks before passing control to the
      driver implementation.  In RFC 2119 vocabulary, this function:
    </p>

    <ol class="ordinarylist">
      <li>SHOULD log a message with VIR_DEBUG() indicating that it is
        being called and its parameters;</li>
      <li>MUST call virResetLastError();</li>
      <li>SHOULD confirm that the connection is valid with
        virCheckConnectReturn() or virCheckConnectGoto();</li>
      <li><strong>SECURITY: If the API requires a connection with write
          privileges, MUST confirm that the connection flags do not
          indicate that the connection is read-only with
          virCheckReadOnlyGoto();</strong></li>
      <li>SHOULD do basic validation of the parameters that are being
        passed in, using helpers like virCheckNonNullArgGoto();</li>
      <li>MUST confirm that the driver for this connection exists and that
        it implements this function;</li>
      <li>MUST call the internal API;</li>
      <li>SHOULD log a message with VIR_DEBUG() indicating that it is
        returning, its return value, and status.</li>
      <li>MUST return status to the caller.</li>
    </ol>

    <p>The public API calls are implemented in:</p>

    <p><code>src/libvirt-$MODULE.c</code></p>

    <h2><a name='remoteproto'>Implementing the remote protocol</a></h2>

    <p>
      Implementing the remote protocol is essentially a
      straightforward exercise which is probably most easily
      understood by referring to the existing code.
    </p>

    <h3><a name='wireproto'>Defining the wire protocol format</a></h3>

    <p>
      Defining the wire protocol involves making additions to:
    </p>

    <p><code>src/remote/remote_protocol.x</code></p>

    <p>
      First, create two new structs for each new function that you're adding
      to the API.  One struct describes the parameters to be passed to the
      remote function, and a second struct describes the value returned by
      the remote function.  The one exception to this rule is that functions
      that return only 0 or -1 for status do not require a struct for returned
      data.
    </p>

    <p>
      Second, add values to the remote_procedure enum for each new function
      added to the API.
    </p>

    <p>
      Once these changes are in place, it's necessary to run 'make rpcgen'
      in the src directory to create the .c and .h files required by the
      remote protocol code. This must be done on a Linux host using the
      GLibC rpcgen program. Other rpcgen versions may generate code which
      results in bogus compile time warnings.  This regenerates the
      following files:
    </p>

    <p><code>
        src/remote/remote_daemon_dispatch_stubs.h
        src/remote/remote_daemon_dispatch.h
        src/remote/remote_daemon_dispatch.c
        src/remote/remote_protocol.c
        src/remote/remote_protocol.h
    </code></p>

    <h3><a name='rpcclient'>Implement the RPC client</a></h3>

    <p>
      Implementing the RPC client uses the rpcgen generated .h files.
      The remote method calls go in:
    </p>

    <p><code>src/remote/remote_driver.c</code></p>

    <p>Each remote method invocation does the following:</p>

    <ol class="ordinarylist">
      <li>locks the remote driver;</li>
      <li>sets up the method arguments;</li>
      <li>invokes the remote function;</li>
      <li>checks the return value, if necessary;</li>
      <li>extracts any returned data;</li>
      <li>frees any returned data;</li>
      <li>unlocks the remote driver.</li>
    </ol>

    <h3><a id="serverdispatch">Implement the server side dispatcher</a></h3>

    <p>
      Implementing the server side of the remote function call is simply a
      matter of deserializing the parameters passed in from the remote
      caller and passing them to the corresponding internal API function.
      The server side dispatchers are implemented in:
    </p>

    <p><code>src/remote/remote_daemon_dispatch.c</code></p>

    <p>Again, this step uses the .h files generated by make rpcgen.</p>

    <p>
      After all three pieces of the remote protocol are complete, and
      the generated files have been updated, it will be necessary to
      update the file:</p>

    <p><code>src/remote_protocol-structs</code></p>

    <p>
      This file should only have new lines added; modifications to
      existing lines probably imply a backwards-incompatible API change.
    </p>

    <h2><a id="internaluseapi">Use the new API internally</a></h2>

    <p>
      Sometimes, a new API serves as a superset of existing API, by
      adding more granularity in what can be managed.  When this is
      the case, it makes sense to share a common implementation by
      making the older API become a trivial wrapper around the new
      API, rather than duplicating the common code.  This step should
      not introduce any semantic differences for the old API, and is
      not necessary if the new API has no relation to existing API.
    </p>

    <h2><a id="virshuseapi">Expose the new API in virsh</a></h2>

    <p>
      All new API should be manageable from the virsh command line
      shell.  This proves that the API is sufficient for the intended
      purpose, and helps to identify whether the proposed API needs
      slight changes for easier usage.  However, remember that virsh
      is used to connect to hosts running older versions of libvirtd,
      so new commands should have fallbacks to an older API if
      possible; implementing the virsh hooks at this point makes it
      very easy to test these fallbacks.  Also remember to document
      virsh additions.
    </p>

    <p>
      A virsh command is composed of a few pieces of code.  You need to
      define an array of vshCmdInfo structs for each new command that
      contain the help text and the command description text.  You also need
      an array of vshCmdOptDef structs to describe the command options.
      Once you have those pieces in place you can write the function
      implementing the virsh command.  Finally, you need to add the new
      command to the commands[] array.  The following files need changes:
    </p>

    <p><code>
        tools/virsh-$MODULE.c<br/>
        tools/virsh.pod
    </code></p>

    <h2><a id="driverimpl">Implement the driver methods</a></h2>

    <p>
      So, after all that, we get to the fun part.  All functionality in
      libvirt is implemented inside a driver.  Thus, here is where you
      implement whatever functionality you're adding to libvirt.  You'll
      either need to add additional files to the src directory or extend
      files that are already there, depending on what functionality you're
      adding.
    </p>

    <h3><a id="commonimpl">Implement common handling</a></h3>

    <p>
      If the new API is applicable to more than one driver, it may
      make sense to provide some utility routines, or to factor some
      of the work into the dispatcher, to avoid reimplementing the
      same code in every driver.  In the example code, this involved
      adding a member to the virDomainDefPtr struct for mapping
      between the XML API addition and the in-memory representation of
      a domain, along with updating all clients to use the new member.
      Up to this point, there have been no changes to existing
      semantics, and the new APIs will fail unless they are used in
      the same way as the older API wrappers.
    </p>

    <h3><a id="drivercode">Implement driver handling</a></h3>

    <p>
      The remaining patches should only touch one driver at a time.
      It is possible to implement all changes for a driver in one
      patch, but for review purposes it may still make sense to break
      things into simpler steps.  Here is where the new APIs finally
      start working.
    </p>

    <p>
      It is always a good idea to patch the test driver in addition to the
      target driver, to prove that the API can be used for more than one
      driver.
    </p>

    <p>
      Any cleanups resulting from the changes should be added as separate
      patches at the end of the series.
    </p>

    <p>
      Once you have working functionality, run make check and make
      syntax-check on each patch of the series before submitting
      patches.  It may also be worth writing tests for the libvirt-TCK
      testsuite to exercise your new API, although those patches are
      not kept in the libvirt repository.
    </p>
  </body>
</html>