Debian Codegraph @

demos/demo_rule9/README

raw
1 1. Motivate in some way the changes that need to be made.
2
3 2. Show the semantic patch in rule9_1.cocci. This could also be developed
4 incrementally, with first the lines for get and put, then the line for
5 the error checking on hostptr, then the - and + line for moving the
6 declaration of hostptr to the parameter list. Finally, drop the hostno
7 parameter. Explain the metavariables. Note that a rule is
8 automatically generated to update the prototype of the proc_info
9 function, if one is available.
10
11 3. Apply it to scsiglue.c and show what has changed.
12
13 4. Some issues:
14
15 * In nsp_cs.c (and a lot of other files), there is no call to the put
16 function. Indeed, the reason for the CE was that driver programmers
17 were forgetting to call the put function. We thus would like to make
18 it optional, the idea being that if we find it we should delete it,
19 but if we don't find it, the rest of the transformation should still
20 take place.
21
22 * In g_NCR5380.c, there is no error checking on the result of calling
23 the get function. Thus, that has to be optional as well. The result
24 of making both of these changes is in rule9_2.cocci.
25
26 * In sym53c8xx.c, there are no braces around the if branch in the error
27 handling code. Explain about the isomorphisms.
28
29 * In nsp_cs.c, hostptr is compared to NULL. There is an isomorphism for
30 that as well.
31
32 * The function is essentially identified by the types of its
33 parameters. Since there are quite a lot of them, with quite varied
34 typed, this is probably enough to uniquely identify the function
35 within each driver in practice. But for greater safety, we should
36 describe the function in terms of how it interacts with the SCSI
37 library, because it is the SCSI library that will be responsible for
38 supplying the extra argument. For this we add a new rule
39 (rule9_3.cocci). This rule identifies the function as the one that is
40 stored in the proc_info field of a structure of type SHT (also given
41 the typedef name of Scsi_Host_Template). Isomorphisms take case of
42 the case where this assignment has other forms, eg involving a pointer
43 to the structure or is part of a top-level structure initialization.
44
45 Now we want to inherit the binding of proc_info_func from the first
46 rule to the second one. For this, we give the first one a name, and
47 use that name in declaring the proc_info_func metavariable in the
48 second rule. The second rule will be applied once for each successful
49 match of the first rule, but in practice, there is only one.
50
51 5. The transformation that is implemented is not yet complete, as one can
52 see by comparing with the .res file. We also have to rename the hostno
53 variable everywhere that it occurs. Because it can in principle occur
54 anywhere, we make a separate rule to avoid cluttering up the previous
55 one. This rule inherits the name of the proc_info function from rule1
56 and the names of the hostno and hostptr variables from rule2. The
57 transformation is to replace occurrences of hostno by a reference to the
58 host_no field of hostptr everywhere hostno occurs, as indicated by the
59 <... ...>.
60
61 6. Finally, the proc_info function may be called from other places within
62 the current driver. These cases must be updated as well with the new
63 argument. For this, we have to find an appropriate value somewhere.
64 Because the get function has been deprecated, the driver will normally
65 get this information as a parameter, and that is the only case we
66 consider here. The name of the function enclosing the call is arbitrary
67 (as indicated by a metavariable) as is the position of the
68 Scsi_Host-typed parameter (as indicated by the dots in the parameter
69 list). As for the previous rule, we use <... ...> to update a call to
70 the proc_info function wherever it occurs. Note that although we have
71 used the same names as for the parameter list in rule2, buffer, start,
72 etc. are now arbitrary expressions.
73