Some versions of doxygen seem to object to "@ret None" or similar.
[people/xl0/gpxe.git] / src / interface / pxe / pxe_udp.c
1 /** @file
2  *
3  * PXE UDP API
4  *
5  */
6
7 #include "pxe.h"
8 #include "io.h"
9 #include "string.h"
10
11 /*
12  * Copyright (C) 2004 Michael Brown <mbrown@fensystems.co.uk>.
13  *
14  * This program is free software; you can redistribute it and/or
15  * modify it under the terms of the GNU General Public License as
16  * published by the Free Software Foundation; either version 2 of the
17  * License, or any later version.
18  *
19  * This program is distributed in the hope that it will be useful, but
20  * WITHOUT ANY WARRANTY; without even the implied warranty of
21  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
22  * General Public License for more details.
23  *
24  * You should have received a copy of the GNU General Public License
25  * along with this program; if not, write to the Free Software
26  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
27  */
28
29 /**
30  * UDP OPEN
31  *
32  * @v udp_open                          Pointer to a struct s_PXENV_UDP_OPEN
33  * @v s_PXENV_UDP_OPEN::src_ip          IP address of this station, or 0.0.0.0
34  * @ret #PXENV_EXIT_SUCCESS             Always
35  * @ret s_PXENV_UDP_OPEN::Status        PXE status code
36  * @err #PXENV_STATUS_UNDI_INVALID_STATE NIC could not be initialised
37  *
38  * Prepares the PXE stack for communication using pxenv_udp_write()
39  * and pxenv_udp_read().  The IP address supplied in
40  * s_PXENV_UDP_OPEN::src_ip will be recorded and used as the local
41  * station's IP address for all further communication, including
42  * communication by means other than pxenv_udp_write() and
43  * pxenv_udp_read().  (If s_PXENV_UDP_OPEN::src_ip is 0.0.0.0, the
44  * local station's IP address will remain unchanged.)
45  *
46  * You can have multiple UDP connections open simultaneously (and
47  * even open concurrently with TFTP connections), provided that
48  *
49  *   - they all have the same local IP address, and
50  *
51  *   - you take the multiple connections into account when calling
52  *     pxenv_udp_read().
53  *
54  * On x86, you can call pxenv_udp_open() in real mode, 16-bit
55  * protected mode with a 16-bit stack segment, 16-bit protected mode
56  * with a 32-bit stack segment, or V86 mode.  The pxe::StatusCallout
57  * field may be zero even in protected mode.
58  * 
59  * @note The PXE specification states that you have only one UDP
60  * connection open at a time, and that you cannot have a UDP
61  * connection open simultaneously with a TFTP connection.  Etherboot
62  * does not enforce this unnecessary restriction.
63  *
64  */
65 PXENV_EXIT_t pxenv_udp_open ( struct s_PXENV_UDP_OPEN *udp_open ) {
66         DBG ( "PXENV_UDP_OPEN" );
67         ENSURE_READY ( udp_open );
68
69         if ( udp_open->src_ip &&
70              udp_open->src_ip != arptable[ARP_CLIENT].ipaddr.s_addr ) {
71                 /* Overwrite our IP address */
72                 DBG ( " with new IP %@", udp_open->src_ip );
73                 arptable[ARP_CLIENT].ipaddr.s_addr = udp_open->src_ip;
74         }
75
76         udp_open->Status = PXENV_STATUS_SUCCESS;
77         return PXENV_EXIT_SUCCESS;
78 }
79
80 /**
81  * UDP CLOSE
82  *
83  * @v udp_close                         Pointer to a struct s_PXENV_UDP_CLOSE
84  * @ret #PXENV_EXIT_SUCCESS             Always
85  * @ret s_PXENV_UDP_CLOSE::Status       PXE status code
86  * @err None                            -
87  *
88  * Closes a UDP "connection" opened with pxenv_udp_open().  Since UDP
89  * is a connectionless protocol, this is a no-op.
90  *
91  * You can call pxenv_udp_close() even if there is another active UDP
92  * or TFTP connection, since it has no effect on anything.
93  *
94  * You can call pxenv_udp_close() in real mode, 16-bit protected mode
95  * with a 16-bit stack segment, 16-bit protected mode with a 32-bit
96  * stack segment, or V86 mode.  The pxe::StatusCallout field may be
97  * zero even in protected mode.
98  *
99  * @note The PXE specification states that you have only one UDP
100  * connection open at a time, and that you cannot have a UDP
101  * connection open simultaneously with a TFTP connection.  Etherboot
102  * does not enforce this unnecessary restriction.
103  *
104  */
105 PXENV_EXIT_t pxenv_udp_close ( struct s_PXENV_UDP_CLOSE *udp_close __unused ) {
106         DBG ( "PXENV_UDP_CLOSE" );
107         udp_close->Status = PXENV_STATUS_SUCCESS;
108         return PXENV_EXIT_SUCCESS;
109 }
110
111 /**
112  * UDP WRITE
113  *
114  * @v udp_write                         Pointer to a struct s_PXENV_UDP_WRITE
115  * @v s_PXENV_UDP_WRITE::ip             Destination IP address
116  * @v s_PXENV_UDP_WRITE::gw             Gateway IP address, or 0.0.0.0
117  * @v s_PXENV_UDP_WRITE::src_port       Source UDP port, or 0
118  * @v s_PXENV_UDP_WRITE::dst_port       Destination UDP port
119  * @v s_PXENV_UDP_WRITE::buffer_size    Length of the UDP payload
120  * @v s_PXENV_UDP_WRITE::buffer         Address of the UDP payload
121  * @ret #PXENV_EXIT_SUCCESS             Packet was transmitted successfully
122  * @ret #PXENV_EXIT_FAILURE             Packet could not be transmitter
123  * @ret s_PXENV_UDP_WRITE::Status       PXE status code
124  * @err #PXENV_STATUS_UNDI_INVALID_STATE NIC could not be initialised
125  * @err #PXENV_STATUS_OUT_OF_RESOURCES  Packet was too large to transmit
126  * @err other                           Any error from pxenv_undi_transmit()
127  *
128  * Transmits a single UDP packet.  A valid IP and UDP header will be
129  * prepended to the payload in s_PXENV_UDP_WRITE::buffer; the buffer
130  * should not contain precomputed IP and UDP headers, nor should it
131  * contain space allocated for these headers.  The first byte of the
132  * buffer will be transmitted as the first byte following the UDP
133  * header.
134  *
135  * If s_PXENV_UDP_WRITE::gw is 0.0.0.0, normal IP routing will take
136  * place (using, for example, the default gateway IP address returned
137  * by the DHCP server).
138  *
139  * If s_PXENV_UDP_WRITE::src_port is 0, port 2069 will be used.
140  *
141  * It is not necessary to call pxenv_udp_open() before using
142  * pxenv_udp_write(), unless you want to change the local station's IP
143  * address.  pxenv_udp_write() can be called even if there is another
144  * active UDP or TFTP connection,.
145  *
146  * You can call pxenv_udp_write() in real mode, 16-bit protected mode
147  * with a 16-bit stack segment, 16-bit protected mode with a 32-bit
148  * stack segment, or V86 mode.  The pxe::StatusCallout field may be
149  * zero even in protected mode.
150  *
151  * @note The PXE specification states that you have only one UDP
152  * connection open at a time, and that you cannot have a UDP
153  * connection open simultaneously with a TFTP connection.  Etherboot
154  * does not enforce this unnecessary restriction.
155  *
156  * @bug s_PXENV_UDP_WRITE::gw is ignored; the default routing table is
157  * always used.
158  *
159  */
160 PXENV_EXIT_t pxenv_udp_write ( struct s_PXENV_UDP_WRITE *udp_write ) {
161         uint16_t src_port;
162         uint16_t dst_port;
163         struct udppacket *packet = (struct udppacket *)nic.packet;
164         int packet_size;
165
166         DBG ( "PXENV_UDP_WRITE" );
167         ENSURE_READY ( udp_write );
168
169         /* PXE spec says source port is 2069 if not specified */
170         src_port = ntohs(udp_write->src_port);
171         if ( src_port == 0 ) src_port = 2069;
172         dst_port = ntohs(udp_write->dst_port);
173         DBG ( " %d->%@:%d (%d)", src_port, udp_write->ip, dst_port,
174               udp_write->buffer_size );
175         
176         /* FIXME: we ignore the gateway specified, since we're
177          * confident of being able to do our own routing.  We should
178          * probably allow for multiple gateways.
179          */
180         
181         /* Copy payload to packet buffer */
182         packet_size = ( (void*)&packet->payload - (void*)packet )
183                 + udp_write->buffer_size;
184         if ( packet_size > ETH_FRAME_LEN ) {
185                 udp_write->Status = PXENV_STATUS_OUT_OF_RESOURCES;
186                 return PXENV_EXIT_FAILURE;
187         }
188         memcpy ( &packet->payload, SEGOFF16_TO_PTR(udp_write->buffer),
189                  udp_write->buffer_size );
190
191         /* Transmit packet */
192         if ( ! udp_transmit ( udp_write->ip, src_port, dst_port,
193                               packet_size, packet ) ) {
194                 udp_write->Status = errno;
195                 return PXENV_EXIT_FAILURE;
196         }
197
198         udp_write->Status = PXENV_STATUS_SUCCESS;
199         return PXENV_EXIT_SUCCESS;
200 }
201
202 /* Utility function for pxenv_udp_read() */
203 static int await_pxe_udp ( int ival __unused, void *ptr,
204                            unsigned short ptype __unused,
205                            struct iphdr *ip, struct udphdr *udp,
206                            struct tcphdr *tcp __unused ) {
207         struct s_PXENV_UDP_READ *udp_read = (struct s_PXENV_UDP_READ*)ptr;
208         uint16_t d_port;
209         size_t size;
210
211         /* Ignore non-UDP packets */
212         if ( !udp ) {
213                 DBG ( " non-UDP" );
214                 return 0;
215         }
216         
217         /* Check dest_ip */
218         if ( udp_read->dest_ip && ( udp_read->dest_ip != ip->dest.s_addr ) ) {
219                 DBG ( " wrong dest IP (got %@, wanted %@)",
220                       ip->dest.s_addr, udp_read->dest_ip );
221                 return 0;
222         }
223
224         /* Check dest_port */
225         d_port = ntohs ( udp_read->d_port );
226         if ( d_port && ( d_port != ntohs(udp->dest) ) ) {
227                 DBG ( " wrong dest port (got %d, wanted %d)",
228                       ntohs(udp->dest), d_port );
229                 return 0;
230         }
231
232         /* Copy packet to buffer and fill in information */
233         udp_read->src_ip = ip->src.s_addr;
234         udp_read->s_port = udp->src; /* Both in network order */
235         size = ntohs(udp->len) - sizeof(*udp);
236         /* Workaround: NTLDR expects us to fill these in, even though
237          * PXESPEC clearly defines them as input parameters.
238          */
239         udp_read->dest_ip = ip->dest.s_addr;
240         udp_read->d_port = udp->dest;
241         DBG ( " %@:%d->%@:%d (%d)",
242               udp_read->src_ip, ntohs(udp_read->s_port),
243               udp_read->dest_ip, ntohs(udp_read->d_port), size );
244         if ( udp_read->buffer_size < size ) {
245                 /* PXESPEC: what error code should we actually return? */
246                 DBG ( " buffer too small (%d)", udp_read->buffer_size );
247                 udp_read->Status = PXENV_STATUS_OUT_OF_RESOURCES;
248                 return 0;
249         }
250         memcpy ( SEGOFF16_TO_PTR ( udp_read->buffer ), &udp->payload, size );
251         udp_read->buffer_size = size;
252
253         return 1;
254 }
255
256 /**
257  * UDP READ
258  *
259  * @v udp_read                          Pointer to a struct s_PXENV_UDP_READ
260  * @v s_PXENV_UDP_READ::dest_ip         Destination IP address, or 0.0.0.0
261  * @v s_PXENV_UDP_READ::d_port          Destination UDP port, or 0
262  * @v s_PXENV_UDP_READ::buffer_size     Size of the UDP payload buffer
263  * @v s_PXENV_UDP_READ::buffer          Address of the UDP payload buffer
264  * @ret #PXENV_EXIT_SUCCESS             A packet has been received
265  * @ret #PXENV_EXIT_FAILURE             No packet has been received
266  * @ret s_PXENV_UDP_READ::Status        PXE status code
267  * @ret s_PXENV_UDP_READ::src_ip        Source IP address
268  * @ret s_PXENV_UDP_READ::dest_ip       Destination IP address
269  * @ret s_PXENV_UDP_READ::s_port        Source UDP port
270  * @ret s_PXENV_UDP_READ::d_port        Destination UDP port
271  * @ret s_PXENV_UDP_READ::buffer_size   Length of UDP payload
272  * @err #PXENV_STATUS_UNDI_INVALID_STATE NIC could not be initialised
273  * @err #PXENV_STATUS_OUT_OF_RESOURCES  Buffer was too small for payload
274  * @err #PXENV_STATUS_FAILURE           No packet was ready to read
275  *
276  * Receive a single UDP packet.  This is a non-blocking call; if no
277  * packet is ready to read, the call will return instantly with
278  * s_PXENV_UDP_READ::Status==PXENV_STATUS_FAILURE.
279  *
280  * If s_PXENV_UDP_READ::dest_ip is 0.0.0.0, UDP packets addressed to
281  * any IP address will be accepted and may be returned.
282  *
283  * If s_PXENV_UDP_READ::d_port is 0, UDP packets addressed to any UDP
284  * port will be accepted and may be returned.
285  *
286  * It is not necessary to call pxenv_udp_open() before using
287  * pxenv_udp_read().  pxenv_udp_read() can be called even if there is
288  * another active UDP or TFTP connection, but be aware that you might
289  * then receive (or cause to be lost) a packet belonging to another
290  * connection.
291  *
292  * You can call pxenv_udp_read() in real mode, 16-bit protected mode
293  * with a 16-bit stack segment, 16-bit protected mode with a 32-bit
294  * stack segment, or V86 mode.  The pxe::StatusCallout field may be
295  * zero even in protected mode.
296  *
297  * @note The PXE specification states that you have only one UDP
298  * connection open at a time, and that you cannot have a UDP
299  * connection open simultaneously with a TFTP connection.  Etherboot
300  * does not enforce this unnecessary restriction.
301  *
302  * @note The PXE specification (version 2.1) does not state that we
303  * should fill in s_PXENV_UDP_READ::dest_ip and
304  * s_PXENV_UDP_READ::d_port, but Microsoft Windows' NTLDR program
305  * expects us to do so, and will fail if we don't.
306  *
307  */
308 PXENV_EXIT_t pxenv_udp_read ( struct s_PXENV_UDP_READ *udp_read ) {
309         DBG ( "PXENV_UDP_READ" );
310         ENSURE_READY ( udp_read );
311
312         /* Use await_reply with a timeout of zero */
313         /* Allow await_reply to change Status if necessary */
314         udp_read->Status = PXENV_STATUS_FAILURE;
315         if ( ! await_reply ( await_pxe_udp, 0, udp_read, 0 ) ) {
316                 return PXENV_EXIT_FAILURE;
317         }
318
319         udp_read->Status = PXENV_STATUS_SUCCESS;
320         return PXENV_EXIT_SUCCESS;
321 }