|
| |
The best way to understand how this language works is to study the examples distributed
with GASP. This documentation is a reference guide and not a tutorial.
 | ||
| Content of a file .pro |
| ||
|
mapper |
The file is a list of mappers constituing the protocol |
|
|
|
| ||
| ||
| Definition of a mapper |
| ||
|
?internal? mapper name = { |
The name will be the one used to create the mapper.
If internal is specified, then the mapper is private to the current file. It
will not show up in the mappers list, some code optimization is done. An internal mapper
can not have checksum and length fields. It is use, for example, to define IP and TCP
options which are described as internal mappers.
|
|
| |
size = expression |
The total size. Use '%computedsize' to let GASP compute it when the
size is variable. |
|
| |
spec = string |
A free text the user can consult when requesting help about the mapper.
Use it for example to indicate some references. |
|
| |
endianess = little | big |
Specify default endianess for the fields. Big endian if not specified |
|
|
|
| |
postdecode = { opaque script in Tcl } | sameas(mapperName) |
A script to execute after a mapper has been anchored with the
decodefrom command. This script is executed before the
the extraction of the next layer as computed by the following field.
The script must return an integer which will be interpreted as the offset
to the next byte which was not decoded.
|
|
| |
nextlayer = expression ?, expression, ...? |
Specify a list of possible next layer mapper.
This information is used by the decodefrom command to automatically construct a
stack of mappers.
The first match will deternime the mapper to use next.
To return the textual representation of a field to match the name of a
known mapper, use the '%string(fieldName)' expression. |
|
| |
list of fields |
The list of all the fields composing the mapper. |
|
|
|
| ||
| ||
| Definition of a field |
| ||
|
field name @ (?absolute? offset, size) = { |
The name will be the one used in the configure command.
The name MUST start with a '-'.
The offset and size are expressions. An expression is any C expression, with
all the operators defined in C.
The offset can use one of the meta-values :
- '%data(offset,size ?,endianess?)' to reference some data in the packet memory.
The offset is relative to the mapper. Endianess can be little or big (default is big).
- '%absdata(offset,size ?,endianess?)' to reference some data in the packet memory.
The offset is absolute from the packet.
- '%seek(offset,size ?,endianess?)' to reference the offset of an already defined field.
- '%follows ?(fieldName)?' to tell GASP to put this field immediatly after
the previous one. This is used with variable length fields. You can optionally specify the
field which is followed (this allow for multiple representation of the same data).
- '%offset(fieldName)' to reference the offset of an already defined field.
- '%currentoffset' to reference the offset of the current field.
- '%value(fieldName)' to get a numerical value from the field.
The field name must respect the following syntax: ?mapper.?field ?(index)?.
- '%string(fieldName)' to get a string from the field.
The offset is computed relative from the mapper. The keyword absolute tell the
program to compute the offset from the beginning of the packet.
The size can use the same meta-values expect '%follows' which
is replaced by '%size' the let GASP compute the size of the field. |
|
| |
type = type ?, (little_endian | big_endian | ondemand), ... ? |
The type of the field. See below for a list of supported types. By default, the data used
for the type is read using the big endian (network order) convention. You can force little
or big endian convention by explicitly saying it.
The little endian data must be 2 or 4 bytes in size and byte-aligned
ondemand specifies to not return the content of the field, but the offset of
the content when getting value, unless for ask for precisely for the field. This as no
effect when setting a value (as we always explicitly access the field).
This works only for blob and mapper types.
By default no alignment is used. If specified, the offset will be incremented
to be aligned on a multiple of the given integer. The aligment is computed
relative to the mapper by default but can be the packet memory or parent mapper
memory. (As now, alignment is not supported for all the type.)
|
|
| |
condition = expression |
if a condition is given, the field will exist only if the condition is verified.
|
|
| |
prettyprint = { opaque script in Tcl } |
the script must return the value used to display the data when using the dump
commands. The script may contains percent-expanded varaibles as explained
in pre- and postdecode.
|
|
| |
help = string |
The string returned to user when using the help command. |
|
| |
default = expression |
A default value which is used to initialize the field.
The special values '%address_ethernet' and '%address_ip' can be used to
get the actual Ethernet and IP addresses of the host running GASP. |
|
|
|
| ||
| ||
| Definition of an array of fixed size elements |
| ||
|
fieldarray name @ (?absolute? offset, size) = { |
The offset is the offset of the beginning of the array.
The size is the size of one element. |
|
| |
nbelements = expression |
Indicates the number of entries in the array.
An error is returned if you try to access an element outside the range 0..nbelements-1. |
|
| |
type = type ?, (little_endian | big_endian | ondemand)? |
Same as a simple field. |
|
| |
help = string |
Same as a simple field. |
|
| |
default = expression |
Same as a simple field. |
|
|
|
| ||
| ||
| Definition of an array of variable size elements |
| ||
|
fieldvariablearray name @ (?absolute? offset, size) = { |
The offset is the offset of the beginning of the array.
The size is the total size allocated for all the elements. |
|
| |
type = type ?, (little_endian | big_endian | ondemand)? |
Same as a simple field. |
|
| |
help = string |
Same as a simple field. |
|
| |
default = expression |
Same as a simple field. |
|
|
|
| ||
|
| Table of supported types |
|
| Empty type |
|
| none |
An empty type. Do nothing when you write a value, returns nothing when
trying to read through it.
|
|
|
|
|
| Binary Large Object |
|
| blob |
A block of 8-bits values. Raw data, not processed by GASP.
You can access a specific range of the blob data (for rading or writing)
using the following notation:
fieldName.(-) to designate the whole blob,
fieldName.(x) to designate the byte x,
fieldName.(x-y) to designate the bytes x to y,
fieldName.(x-) to designate the bytes x to the end,
fieldName.(-y) to designate the bytes up to y.
|
|
|
|
|
| Integer |
|
| integer |
An integer value. The integer of 4, 8, 16 and 32 bits have special
optimized routines for read/write. The access to integer at random offset
and of random size is less efficient.
Reading: return a signed integer.
Writing: you can use decimal, hexadecimal (prefix 0x) or octal
(prefix 0) values.
|
|
1234
-56
0xABCD
0777 |
|
| length |
Integer value with a special meaning : compute the length of all the data
forming the packet after the mapper.
Reading: return a signed integer.
Writing: you can use decimal, hexadecimal (prefix 0x) or octal
(prefix 0) values. Use the length command to automatically
set the field to its correct value.
|
|
|
|
checksum(crc_16 ?,size?)
checksum(ip)
checksum(tcp)
checksum(udp)
checksum(iso3309,size ?,offset?) |
Integer value with a special meaning : compute a checksum
using the specified algorithm.
crc_16 compute the 16 bit one's complement of the one's
complement sum of all 16 bit words. If size is not specified, all the data
from the current mapper to the end of the packet are used.
iso3309 compute a CRC using standard CRC methods with pre and
post conditioning, as defined by ISO 3309 or ITU-T V.42. size is the
total size to use and offset is the offset where to start the CRC
(0 by default).
Reading: return a signed integer.
Writing: you can use decimal, hexadecimal (prefix 0x) or octal
(prefix 0) values. Use the setchecksum command to automatically
set the field to its correct value.
|
|
|
|
|
| Strings |
|
| string(fixed) |
A string of fixed size.
Reading: return a string.
Writing: give a string as argument. If the string is too long
to fit in the fixed size, it is truncated. If the string is too short,
the remaing space is fill with 0.
|
|
"toto"
"\t tab"
"new\nline" |
|
string(c)
string(c, unicode) |
A string terminated with a 0, as in the C language.
Reading: return a string.
Writing: give a string as argument. The string fill all the
space for the field. The following data will be moved if necessary.
|
|
"toto"
"\t tab"
"new\nline" |
|
| string(dns) |
A string representing the name of a machine as defined in the DNS
protocol. The compression of string is supported. Extended label
(RFC 2673) not supported.
Reading: return a string.
Writing: give a string as argument. The string fill all the
space for the field. The following data will be moved if necessary.
|
|
"host.domain.country"
"1.2.3.4.inaddr-arpa" |
|
| string(user, ending) |
A string with a user-defined matching string as termination. The 'string(c)'
is a special case with ending = "\0".
Reading: return a string.
Writing: give a string as argument. The string fill all the
space for the field. The following data will be moved if necessary.
|
|
|
|
|
| Encoded integer |
|
| encoded_int(size,base) |
A string representation of an integer.
size is the size of the field (negative value means '\0'
terminated as in C strings). This size is used as the width of the
string used to hold the number (except -1 which means no width).
base is the base used to code the data. 0 means the base will
be guessed while reading (using 0x and 0 prefix) and decimal will be used
for writing. Accepted values : 0, 8, 10 or 16.
Reading: return the string with getraw else return the integer value.
Writing: with setraw, write directly the string in the slot.
Else convert the integer into string.
|
|
|
|
|
| Lists |
|
list {
value short ?long?
...
} |
Describe a list of know values. Each value is associated with a short and
a long description. The values are directly stored in an array for
the best runtime performance.
Reading: returns the short description or an integer if the
value doesn't map to a know value. Use getraw
to get the numerical value and getverbose
to get the long description (long=short is not given).
Writing: accepts the short description as input or any form
of number.
|
|
|
|
sparelist {
value short ?long?
...
} |
Same as above, but stores data more efficiently when the list if not
composed of contiguous values. There is a small runtime penality as
the program must lookup for the value.
|
|
|
|
| samelist(name ?,mapper?) |
Use this type to indicate that the field is using the same list as an
other field. The type share the data with the field given in name (the
field can be in another mapper).
|
|
|
|
|
| Flags |
|
list {
mask name off on
...
} |
Describes a list of flags. Each flag is define by a mask, its name, and
a long description for the clear and set states.
Reading: returns a list of flags names prefixed by '-' is the
flag is cleared and '+' if it is set.
Use getraw to get the numerical value and
getverbose to get a long description.
Writing: needs a list of flags to change. '+name' or 'name'
means 'set the flag' and '-name' means 'clear the flag'.
Any flag not mentionned in the list is left unmodified.
If an integer is given, the value is directly written
into the memory.
|
|
{+a -b +e} |
|
|
| Addresses |
|
| address_ethernet |
An ethernet address represented as 6 bytes separated by columns.
is a special case with ending = "\0".
Reading: return a string.
Writing: expect 6 bytes separated by columns.
|
|
12:34:56:78:9A:BC |
|
| address_ip |
An IP address. The resolution uses the DNS services.
Reading: returns the hostname. Use getraw
to obtain the dotted value and getverbose
to get the fully qualified name.
Writing: any form accepted by a DNS request will work.
|
|
1.2.3.4
host
host.domain |
|
|
| Structures |
|
record {
sybtype(size)
...
} |
Allows to group severals basic types in one. The subtype must be
a valid type and the size is the size of the subtype inside the
total side of the field.
The subtype are simply appended.
A record can't contain variable lengh types.
Reading: returns a list of the values of the subtypes.
Writing: a list of values rescpecting the input conventing
for each subtype.
|
|
|
|
| mapper(name) |
For complex types, use an other mapper to decode/encode it.
Reading: same as the mapper used.
Writing: same as the mapper used.
|
|
|
|
switch(expression) {
v1-v2 type
v1,v2 type
...
default type
} |
Handles dynamic typing. The type used to read/write the value is
determined at run-time using the value of the given expression.
This value is matched against a list of possible value. Is none is
matched, a default type is used (the default must be specified).
If the size is '%variable' and integer types are included
as decoders, their size must be given using the notation
integer(size).
The matching values can be multiple and contain ranges.
Reading: same as the matched type.
Writing: same as the matched type.
|
|
|
|
strswitch(expression ?, expr, ...?) {
s1 type
s1,s2 type
...
default type
} |
Handles dynamic typing. The type used to read/write the value is
determined at run-time concatenong the string given in arguments.
This value is matched against a list of possible value. Is none is
matched, a default type is used (the default must be specified).
If the size is '%variable' and integer types are included
as decoders, their size must be given using the notation
integer(size).
The matching values can be multiple.
Reading: same as the matched type.
Writing: same as the matched type.
|
|
|
|
|
:PAGE_BODY] | | |
%p is replaced by the current packet name
