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
|
$Id: packetdescription.txt 4772 2010-01-02 06:10:24Z djpham $
This is a description of how to use the packet description language. Here is a
sample:
=================================================================================
%{
# Text in this block is placed in the output file
from prototypes import *
# map all UINT fields to lsb version
UINT=UINTlsb
BOOL=BOOLlsb
%}
PACKET {'errorcode': 0, 'bar': "a test}",
'zz': 3} brewreadresponse:
""" a description of this packet
across multiple
lines"""
P UINT thetype "some sort of type"
1 UINT {'constant': 0x59} brewheader "header byte"
1 UINT brewreadcommand
1 UINT errorcode
1 UINT block_number "this wraps at 0xff to 0x01"
if self.thetype==1:
1 UINT there_is_more
elif self.thetype==2:
* STRING some_string
else:
2 BOOL some_bool
2 UINT size
2 UINT {'value': self.size+2} +computedsize
* DATA {'size': self.type, 'test': {'test2': 'x', 'test3': "help"}} data
if self.type==3:
* phonebookentryreadresponse {'fred': 112} rr
1 UINT somethingelse
* LIST {'elementclass': ADifferentClass, 'length': self.size} list1
* LIST list2:
4 UINT field1
27 STRING field2
"""Embedded code"""
%{
def test(self):
print 'this is a test'
def test2(self, v):
print 'this is another test',v
return True
%}
=================================================================================
The general format is that parameters/customisation of a field or type is
done by supplying them in a dict. See the doc in the init methods of each
type for what they know about.
A packet is described by the PACKET keyword, an optional dict of parameters,
the name and a colon. The packet name may have optional modifiers.
A modifier of '-' means that this packet is a "Read-From-Buffer-Only" packet,
i.e., you don't use this packet to write stuff back out to the phone.
The packet description is then indented one level.
Each line is a field description:
size type {optionalparams} name "optionalcomment"
A size of P means it is a packet parameter and not part of the actual data.
For example you may use a field like this to distinguish between read and
write versions of a packet that are very similar. The example shows
the there_is_more field only being present if thetype is greater than 1.
A value of '*' means it is not a fixed length. Use integers for fixed
length fields.
The type is one of the primitive types, or another packet. Most are defined
in prototypes.py
The name may have some optional modifiers.
A modifier of '+' means the field will be created when being written out automatically.
In this example, computedsize depends on the value of another field. You will
generally want to use the '+' modifier for all fields with a computed value.
A modified of '*' means that the dict is only supplied when writing, not reading.
You will need to use this if the dict contains references to stuff further
in the packet, since they won't exist while reading.
The name may be ommited, which indicates an anonymous/nameless field. Anonymous
fields will not be accessible (no get/set property). Anonymous fields (along
type DONTCARE), are typically used for block of data that we don't care about.
The optional comment will appear in the API documentation for the field.
For lists, you can specify what the type of the elements is as is
done for list1. You can also make following lines be indented and
an automagically named class will be created and the elementclass
name automatically supplied.
DO NOT NAME ANY FIELDS AFTER A PYTHON BUILTIN NAME SUCH AS type, dict, str.
IF YOU DO, WIERD THINGS WILL HAPPEN.
|
