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
|
description of distcc protocol version 1
Copyright (C) 2003 by Martin Pool
disclaimer
----------
This document is provided as explanation for people developing or
debugging distcc. Discrepancies between this document and the distcc
code are an error in the document.
This document is intended to describe distcc 2.0.
Because this program and document is licensed free of charge, there is
no warranty of any kind, to the extent permitted by applicable law.
If anything is unclear, please ask on the mailing list.
purpose
-------
The distcc protocol allows a compiler command line plus C preprocessed
source code to be transmitted from a client computer to a server,
where it is compiled. The results (object code, exit status, and/or
error messages) are returned to the client.
protocol versioning
-------------------
This document describes version 1 of the protocol, which is used by
distcc releases up to and including 2.1.
Future versions of the protocol may vary in any way.
The client begins its request by identifying the protocol version that
it will use. The server must either respond using the requested
protocol version, or respond with an error in the appropriate protocol
version, or drop the connection.
There is no mechanisms for negotiation of versions.
It is envisaged that when software using a new protocol is released,
users will upgrade both clients and servers at the same time. Since
distcc is only used within organizations rather than on the internet
this should be realistic.
foundations
-----------
The distcc protocol runs over a bidirectional non-delimited byte
channel. This is normally a TCP connection, although operation over
the OpenSSH secure shell is also supported.
Each compilation of a file ("job") corresponds to one invocation of
the client program and connection.
control flow
------------
The overall structure of the protocol is very simple:
1: The client opens a connection, which is accepted by the server.
2: The client sends a request.
3: The server sends a response.
4: The client and server mutually close the connection.
connections
-----------
Connections are initiated by the client. TCP connections are opened
by connecting to the server port, normally 3632. SSH connections are
initiated by running the command "distccd --inetd" over SSH.
Either party (client or server) may drop the connection at any point,
in which case the job is discarded by both parties. In particular,
the server drops the connection if the client's IP address is not
allowed to connect, or if the client makes a protocol error.
packets
-------
The request and response both consist of a series of packets. Each
packet consists of two or three parts:
token -- four ascii bytes, defining the type of the packet
parameter -- eight ascii hexadecimal digits, corresponding to a
32-bit unsigned quantity
body -- optionally present, depending on the token
The sequence in which tokens are sent by both client and server is
always fixed and is specified by this document.
If the type of packet (determined by the token) requires a body, then
the length of the body is given by the parameter. Otherwise, the
meaning of the parameter depends on the token.
Closing the channel has no meaning and does not indicate the end of a
packet, although it should correspond with the end of the last packet.
An early close indicates an error.
[note: Because the sequence of tokens never varies they are strictly
redundant: each party could just read the parameters and bodies in
order and know what they mean from context. Sending the tokens
provides a check that both parties understand the data to mean the
same thing and guards against code or network errors. It also aids
any person examining the network stream.]
[note: Sending the parameter as hexadecimal is redundant, because four
bytes would be sufficient to encode the 32-bit integer. Sending as
hexadecimal serves as a futher check that the client and server are
synchronized. Incorrect values for the parameter are detected as a
program or network error.]
[note: The fixed length of the token and length-preceded body allows
IO with a small number of system calls: the header can be read in
exactly twelve bytes, and the body can be read in a single chunk
without needing to parse its contents.]
[note: The length-preceded format means that data cannot be streamed
out until the process that produced it is complete and the length of
the data is known.]
request
-------
The following packets comprise the request:
DIST <version>
Greeting from client, followed by the protocol version, which is
always 1.
ARGC <nargs>
Specifies the number of arguments in the command, including the
compiler name.
ARGV <len> <bytes>
Repeated <nargs> times. Specifies the string value of one element
of the command.
DOTI <len> <bytes>
The contents of the preprocessed source (.i) file.
response
--------
The following packets comprise the response:
DONE <version>
Introduces the response. The version must be 1.
STAT <status>
Gives the Unix wait status of the compiler. This 0 for success,
or otherwise (EXITCODE << 8) | (TERMSIGNAL), depending on whether
the compiler returned an error or was terminated by a signal.
(See <sys/wait.h> or a POSIX standard for a full definition.)
SERR <len> <bytes>
Contains messages sent to stderr by the compiler.
SOUT <len> <bytes>
Contains messages sent to stdout by the compiler. Normally empty
-- errors and warnings for most compilers go to stderr instead.
DOTO <len> <bytes>
Contains the object file (.o) produced by the compiler.
In very early versions, this is missing if the status code is not
zero.
In versions up to and including 2.7.1, zero-length output files
are not supported. If compilation fails, then the server sends
the file with a length of zero, but the client does not read it.
From 2.8, things work as follows:
regular success:
status zero
length nonzero
succeeded, but zero-byte output:
status zero
length zero
output file is created/touched
failed:
status nonzero
length sent as zero
This is a little complex but is compatible with earlier releases.
This does mean we cannot represent a compiler that produces output
and then fails, but I don't think that is very important.
|
