Date: Fri, 25 Jan 2013 11:51:29 +0000 (UTC) From: Sean Bruno <sbruno@FreeBSD.org> To: src-committers@freebsd.org, svn-src-user@freebsd.org Subject: svn commit: r245904 - in user/sbruno/pxe_http-gsoc2007: . project project/i386_mod project/libi386_mod project/libstand_mod project/loader_mod Message-ID: <201301251151.r0PBpTHE056739@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: sbruno Date: Fri Jan 25 11:51:28 2013 New Revision: 245904 URL: http://svnweb.freebsd.org/changeset/base/245904 Log: Drop in the contents of the 2007 gsoc code that was submitted at the end of the project. This code compiles/works under 6current from that time frame. Added: user/sbruno/pxe_http-gsoc2007/INFO user/sbruno/pxe_http-gsoc2007/project/ user/sbruno/pxe_http-gsoc2007/project/Makefile user/sbruno/pxe_http-gsoc2007/project/README user/sbruno/pxe_http-gsoc2007/project/httpfs.c user/sbruno/pxe_http-gsoc2007/project/httpfs.h user/sbruno/pxe_http-gsoc2007/project/i386_mod/ user/sbruno/pxe_http-gsoc2007/project/i386_mod/Makefile user/sbruno/pxe_http-gsoc2007/project/libi386_mod/ user/sbruno/pxe_http-gsoc2007/project/libi386_mod/Makefile user/sbruno/pxe_http-gsoc2007/project/libi386_mod/pxe.c user/sbruno/pxe_http-gsoc2007/project/libi386_mod/pxe.h user/sbruno/pxe_http-gsoc2007/project/libstand_mod/ user/sbruno/pxe_http-gsoc2007/project/libstand_mod/printf.c user/sbruno/pxe_http-gsoc2007/project/libstand_mod/stand.h user/sbruno/pxe_http-gsoc2007/project/loader_mod/ user/sbruno/pxe_http-gsoc2007/project/loader_mod/Makefile user/sbruno/pxe_http-gsoc2007/project/loader_mod/conf.c user/sbruno/pxe_http-gsoc2007/project/loader_mod/loader.rc user/sbruno/pxe_http-gsoc2007/project/loader_mod/main.c user/sbruno/pxe_http-gsoc2007/project/pxe_arp.c user/sbruno/pxe_http-gsoc2007/project/pxe_arp.h user/sbruno/pxe_http-gsoc2007/project/pxe_await.c user/sbruno/pxe_http-gsoc2007/project/pxe_await.h user/sbruno/pxe_http-gsoc2007/project/pxe_buffer.c user/sbruno/pxe_http-gsoc2007/project/pxe_buffer.h user/sbruno/pxe_http-gsoc2007/project/pxe_connection.c user/sbruno/pxe_http-gsoc2007/project/pxe_connection.h user/sbruno/pxe_http-gsoc2007/project/pxe_core.c user/sbruno/pxe_http-gsoc2007/project/pxe_core.h user/sbruno/pxe_http-gsoc2007/project/pxe_dhcp.c user/sbruno/pxe_http-gsoc2007/project/pxe_dhcp.h user/sbruno/pxe_http-gsoc2007/project/pxe_dns.c user/sbruno/pxe_http-gsoc2007/project/pxe_dns.h user/sbruno/pxe_http-gsoc2007/project/pxe_filter.c user/sbruno/pxe_http-gsoc2007/project/pxe_filter.h user/sbruno/pxe_http-gsoc2007/project/pxe_http.c user/sbruno/pxe_http-gsoc2007/project/pxe_http.h user/sbruno/pxe_http-gsoc2007/project/pxe_icmp.c user/sbruno/pxe_http-gsoc2007/project/pxe_icmp.h user/sbruno/pxe_http-gsoc2007/project/pxe_ip.c user/sbruno/pxe_http-gsoc2007/project/pxe_ip.h user/sbruno/pxe_http-gsoc2007/project/pxe_isr.S user/sbruno/pxe_http-gsoc2007/project/pxe_isr.h user/sbruno/pxe_http-gsoc2007/project/pxe_mem.c user/sbruno/pxe_http-gsoc2007/project/pxe_mem.h user/sbruno/pxe_http-gsoc2007/project/pxe_segment.c user/sbruno/pxe_http-gsoc2007/project/pxe_segment.h user/sbruno/pxe_http-gsoc2007/project/pxe_sock.c user/sbruno/pxe_http-gsoc2007/project/pxe_sock.h user/sbruno/pxe_http-gsoc2007/project/pxe_tcp.c user/sbruno/pxe_http-gsoc2007/project/pxe_tcp.h user/sbruno/pxe_http-gsoc2007/project/pxe_udp.c user/sbruno/pxe_http-gsoc2007/project/pxe_udp.h Added: user/sbruno/pxe_http-gsoc2007/INFO ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ user/sbruno/pxe_http-gsoc2007/INFO Fri Jan 25 11:51:28 2013 (r245904) @@ -0,0 +1,30 @@ +Here is 'http support for PXE' project snapshot at 19th of August +(last submit during GSoC). + +There was post GSoC submit and may be will be ready next changes at time you are +reading this sentence, so repository contents differs from this tarball. Also, +deleted at the end phase of project files (e.g. pxe_mutex module) and unused +after all (btx_mod directory) are not included to this tarball. + +Other related (may be even useful) info may be found at: + + * blog.freebsdish.org/taleks + - project related blog + + * wiki.freebsd.org/http_support_for_PXE + - wiki project page + + * perforce.freebsd.org/depotTreeBrowser.cgi?FSPC=//depot/projects/soc2007/taleks%2dpxe%5fhttp&HIDEDEL=NO + - web interface to perforce repository with project + + +Directories structure: + + pxe_http library, main developed code: + /project/*.* + + also, there were made changes to already existed code: + /project/libstand_mod - modified files of libs/libstand library + /project/loader_mod - modified files of i386/loader code + /project/libi386_mod - modified files of i386/libi386 + /project/i386_mod - modified Makefile of i386 folder Added: user/sbruno/pxe_http-gsoc2007/project/Makefile ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ user/sbruno/pxe_http-gsoc2007/project/Makefile Fri Jan 25 11:51:28 2013 (r245904) @@ -0,0 +1,46 @@ +# pxe_http project +# +LIB= pxe_http +INTERNALLIB= + +SRCS= pxe_isr.S pxe_mem.c pxe_buffer.c pxe_await.c pxe_arp.c pxe_ip.c \ + pxe_core.c pxe_icmp.c pxe_udp.c pxe_filter.c pxe_dns.c \ + pxe_dhcp.c pxe_segment.c pxe_tcp.c pxe_sock.c \ + pxe_connection.c pxe_http.c httpfs.c + +CFLAGS+= -I${.CURDIR}/../../common -I${.CURDIR}/../btx/lib \ + -I${.CURDIR}/../../../contrib/dev/acpica \ + -I${.CURDIR}/../../.. -I. -I$(.CURDIR)/.. -I${.CURDIR}/../libi386/ +# the location of libstand +CFLAGS+= -I${.CURDIR}/../../../../lib/libstand/ + +#debug flag +#CFLAGS+= -DPXE_DEBUG +#CFLAGS+= -DPXE_DEBUG_HELL + +# core module debug +#CFLAGS+= -DPXE_CORE_DEBUG_HELL +#CFLAGS+= -DPXE_CORE_DEBUG +# TCP module debug +#CFLAGS+= -DPXE_TCP_DEBUG +#CFLAGS+= -DPXE_TCP_DEBUG_HELL +# IP module debug +#CFLAGS+= -DPXE_IP_DEBUG +#CFLAGS+= -DPXE_IP_DEBUG_HELL +# ARP module debug +#CFLAGS+= -DPXE_ARP_DEBUG +#CFLAGS+= -DPXE_ARP_DEBUG_HELL +# httpfs module +#CFLAGS+= -DPXE_HTTP_DEBUG +#CFLAGS+= -DPXE_HTTP_DEBUG_HELL + +# define to get more PXE related code and testing functions +#CFLAGS+= -DPXE_MORE + +# define to get some speed up by bigger requests +CFLAGS+= -DPXE_HTTPFS_CACHING + +# define to send packets freqently to speed up connection +#CFLAGS+= -DPXE_TCP_AGRESSIVE + +.include <bsd.lib.mk> Added: user/sbruno/pxe_http-gsoc2007/project/README ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ user/sbruno/pxe_http-gsoc2007/project/README Fri Jan 25 11:51:28 2013 (r245904) @@ -0,0 +1,1253 @@ +Contents +---------- + +1. Introduction + + 1.2. Setting up + + 1.2.1. DHCP configuration + 1.2.2. TFTP configuration + 1.2.3. Web-server configuration + 1.2.4. loader.rc configuratuion + +2. Project organisation + + 2.1. Code modules + 2.2. Naming conventions + 2.3. Understanding logical structure of code + +3. API usage + + 3.1. Base information + 3.2. PXE sockets API overview + + 3.2.1. PXE API socket details + + 3.3. Quick Reference to API, available for user code + + 3.3.1. pxe_arp module + 3.3.2. pxe_await module + 3.3.3. pxe_buffer module + 3.3.4. pxe_connection module + 3.3.5. pxe_core module + 3.3.6. pxe_dhcp module + 3.3.7. pxe_dns module + 3.3.8. pxe_filter module + 3.3.9. pxe_http module + 3.3.10. httpfs module + 3.3.11. pxe_icmp module + 3.3.12. pxe_ip module + 3.3.13. pxe_isr module + 3.3.14. pxe_mem module + 3.3.15. pxe_sock module + 3.3.16. pxe_segment module + 3.3.17. pxe_tcp module + 3.3.18. pxe_udp module + +4. Debugging, testing and tuning pxe_http library. + + 4.1. Using 'pxe' loader's command + 4.2. Defining debug macroses + 4.3. Tuning + 4.4. NFS loading with pxe_http + +1. Introduction +---------------- + + pxe_http library is user space implementation of simplified + TCP/IP4 stack with support of sockets. Socket implementation is similar + to common sockets, but differs, so I call this variant of sockets - + "PXE sockets" + + features (read: simpliest ever implementation of): + * supports TCP/UDP PXE sockets + * DHCP client + * DNS client + * http based filesystem + * ICMP echo + +1.1. Requirements +------------------ + + To use pxeboot with extensions from pxe_http library + you need: + * DHCP server + - any DHCP server with support of some options + (see below). In example of configuration files + ISC DHCP v.3.0.5 was used. + * TFTP server + * Web server - I've used Apache 1.3.34 + + +1.2. Setting it up +------------------- + + In most cases, it's the same as for usual pxeboot. Main + difference is in configuration file of DHCP server and in usage of + Web-server. + + +1.2.1. DHCP configuration +------------------------- + + Here is example of configuration: + + # /etc/dhcpd.conf example + # + ddns-update-style none; + server-name "DHCPserver"; + server-identifier 192.168.0.4; + default-lease-time 7200; + max-lease-time 7200; + + # + # significant options for correct working of pxeboot + # + + # your LAN subnet mask + option subnet-mask 255.255.255.0; + + # default gateway to use + option routers 192.168.0.1; + + # name of file to download via TFTP + filename "pxeboot"; + + # name server, used for resolving of domain names + option domain-name-servers 192.168.0.1; + + # ip address of web server + option www-server 192.168.0.2; + + # path, where nessesary files are stored on web server + option root-path "th.lan:/path/to/root"; + + subnet 192.168.0.0 netmask 255.255.255.0 { + next-server 192.168.0.4; + range 192.168.0.10 192.168.0.20; + } + + /* end of example */ + + NOTES: + 1. www-server option is used only if root-path is absent in + DHCP reply. In that case assumed, that /boot directory is + placed in DocumentRoot of web-server. + 2. format of root-path has such format: "server:/path". It's + possible use both IP's and domain names for server. /path is + relative to DocumentRoot of web-server. In example above + files are stored at /usr/local/www/data/path/to/root, + assuming that /usr/local/www/data - is DocumentRoot. + 3. DHCP options are not greater then 255 bytes. So, root-path + must satisfy this requirement. + + +1.2.2. TFTP configuration +-------------------------- + + Same as usually. pxe_http doesn't directly use this protocol. + + +1.2.3. Web-server configuration +-------------------------------- + + Just copy all from "/boot" directory to + /DocumentRoot/path/to/root. + + NOTES: + 1. Need to be sure, that partial downloading and keep-alive + connections are supported by server. e.g. for Apache 1.x, + check this options: + + KeepAlive On + MaxKeepAliveRequests 10 # well, choose best for + # server + KeepAliveTimeout 15 # more then 2 seconds + # is good enough + + 2. loader checks gzipped versions of files first, it's good + idea to compress every needed file. e.g. + beastie.4th.gz + device.hints + frames.4th.gz + loader.4th.gz + loader.conf + loader.help.gz + loader.rc + mfsroot.gz + screen.4th.gz + support.4th.gz + /kernel/kernel.gz + +1.2.4. loader.rc configuratuion +-------------------------------- + + HTTP downloading of kernel is not all need to startup system + correctly. The main question is where will be root filesystem after + booting of kernel. The simpliest way - is to use RAM drive with + installation tools or ready to work system. + Here is example of changes to loader.rc, that instructs loader + to download RAM-drive image (in this example, common mfsroot.gz found + in boot.flp floppy image file) + + + \ Includes additional commands + include /boot/loader.4th + + \ Reads and processes loader.conf variables + start + + \ Tests for password -- executes autoboot first if a password was defined + check-password + + \ Load in the boot menu + include /boot/beastie.4th + + \ pxe_http changes: + echo "loading RAM-drive image" + load -t mfs_root /boot/mfsroot + set vfs.root.mountfrom="ufs:/dev/md0c" + \ + + \ Start the boot menu + beastie-start + + /* end of example */ + + Of course, it's possible to set any other filesystem to work + as root, e,g, NFS and not use RAM drive. + +2. Project organisation +------------------------ + +2.1. Code modules +------------------ + + All project code is divided into following modules: + pxe_arp - ARP protocol (3.3.1) + pxe_await - provides functions for awaiting (3.3.2) + pxe_buffer - implements cyclic buffers (3.3.3) + pxe_connection - TCP connection related functions (3.3.4) + pxe_core - provides calls to PXE API (3.3.5) + pxe_dhcp - DHCP client (3.3.6) + pxe_dns - DNS client (3.3.7) + pxe_filter - incoming packet filters (3.3.8) + pxe_http - HTTP related functions (3.3.9) + httpfs - http based file system (3.3.10) + pxe_icmp - ICMP protocol (3.3.11) + pxe_ip - IP protocol (3.3.12) + pxe_isr - assembler side support for PXE API + calling (3.3.13) + pxe_mem - memory work routines (3.3.14) + pxe_sock - simple sockets (3.3.15) + pxe_segment - TCP segments (3.3.16) + pxe_tcp - TCP protocol (3.3.17) + pxe_udp - UDP protocol (3.3.18) + +2.2. Naming conventions +------------------------ + + Most of functions, that may be called directly by user API uses + pxe_ prefix. + Functions related to some module have subprefix of this module, + e.g. pxe_dhcp_query() - function related to DHCP module. + All structures, that are used have typedef equivalent with + naming in upper case. e.g. struct pxe_ipaddr has equivalent PXE_IPADDR. + This is done to have similar to existing pxe.h declarations from libi386. + + +2.3. Understanding logical structure of code +--------------------------------------------- + + Logicallly all modules may be divided to parts. + + Part 1: PXE API related modules (pxe_isr, pxe_core) + Part 2: base protocols related (pxe_ip, pxe_udp) + Part 3: sockets related (pxe_sock) + Part 4: other protocols (pxe_dns, pxe_dhcp) + Part 5: utility (pxe_mem, pxe_buffer) + + Some modules may be used independently, other depend on some + lower level modules. + + In run-time, many calls to sockets functions start packet + recieving or packet sending functions. Sending is more simplier and may + be assumed in many cases just as wrappers to PXE API. But receiving is + a little bit more complicated. Receiving functions start + pxe_core_recv_packets() function in cycle to get packets. + After receiving of packet, it's handling depends on it's type: + ARP, IP or other. ARP packets directly provided to handler + pxe_arp_protocol(), IP packets are provided to registered handler of IP + stack protocol, other packets are ignored. + Registration of handler (except ARP) is performed during + initialisation time of module with usage of pxe_core_register() function, + which register handler for IP stack protocol number. + So, packet is provided to handler, but it may be fragmented, + thus before processing it must be recieved completely. But in some cases + packet may be not interesting for protocol (unexpected packet, dublicated + or something else) and it's possible to determiny if this packet useful + just by examining of packet header. + If packet is fragmented - it firstly provided to handler with + flag PXE_CORE_FRAG. Handler returns appropriate value if is interested in + whole packet, packet is read completely from input queue of fragments and + provided again with flag PXE_CORE_HANDLE. Otherwise packet is dropped + in core by reading of all it's fragments from incoming queue. + Packet structure provides just buffer with received packet and + size of packet. All pxe_core module send/recieve functions work with + PXE_PACKET structure. + TCP and UDP protocols are checking filters in theirs handlers. + This helps to filter out packets that are not interesting for protocol + (e.g. to port that is not listening) + Socket and filter structures are separated. Socket provides + buffers for incoming and outcoming data. Filters may be used without + sockets, e.g. for TCP connections in TIME_WAIT state. For active + connection filter is used to determiny in which receiving buffer (in + which socket) must be placed incoming data. + + +3. API usage +------------- + + Here much attention paid to sockets, other pxe_http API + may be used less frequently. + +3.1. Base information +----------------------- + + User code must perform initialisation of pxe_core module (which + is performed currently in loader during pxe_enable() call). After this + sockets related functions become available. + + pxe_core_init() performs initialisation of pxe_core module and starts + initialisation routines of other modules. It inits TCP, UDP, ARP and + etc modules, however in most of cases it's possible skip theirs + initialisation if module's functions are unused. + Work is finished by pxe_core_shutdown() function. + + +3.2. PXE sockets API overview +------------------------------- + + PXE sockets API differs from common sockets. It's more simplier + and has some limitations due user space implementations. All socket + related functions are declared in pxe_sock.h header + + Socket is created by pxe_socket() call. After usage socket must + be closed by pxe_close() call. Result of pxe_socket() is integer + descriptor associated with socket. After creating socket is unbinded + and not connected. + pxe_sendto(), pxe_connect(), pxe_bind() functions performs + binding and connecting. After successful calling of one of them - socket + is in active state. It's possible to perform reading and sending from/to + socket. Cause socket API may use buffers to optimize packet sending + process, user code must call pxe_flush() functions to be sure, that + data is really processed to sending module. + While receiving need to keep in memory, that if UDP datagram is + not readed completely by one call of pxe_recv() in this implementation + rest of datagram is omited and lost for user code. + All incoming and outcoming data is written to socket buffers, + that have default sizes 16Kb and 4Kb. If buffers are full, next calls + related to writing or reading data will fail. + + +3.2.1. PXE API socket details +------------------------------ + + /* Here is simple example of API usage. */ + + int socket = pxe_socket(); + /* if result is not -1, then socket variable contains value, + * assosiated with socket structure. Call differs from common sockets, + * there are no domain, type and protocol parameters. + * Cause domain is always AF_INET now. others are use in pxe_connect() + * call. + */ + + int result = pxe_connect(socket, &hh->addr, 80, PXE_TCP_PROTOCOL); + /* This call creates filter, associates it with socket and establishes + * communication if needed. + * Parameters are socket, remote ip address (PXE_IPADDR)m remote port + * and one of PXE_UDP_PROTOCOL and PXE_TCP_PROTOCOL protocols. + */ + + if (result == -1) { + pxe_close(socket); + /* any socket must be closed, even if it was not really used + * or conencted. pxe_close() call releases used internal + * structures. After this call any other operations with + * 'socket' descriptor are invalid. + */ + return (0); + } + + /* pxe_send() function sends data to socket. As usual, there is no + * guarantee, that whole buffer is transmited. And actually for TCP + * protocol, this call just places data to buffer. User code have no + * knowledge if data is really sent to network. if current segment is + * not fullly used, data may stay in buffer infinitely. + */ + if (len != pxe_send(socket, hh->buf, len)) { + /* failed to send data, at least whole buffer */ + pxe_close(socket); + return (0); + } + + /* if user code need guarantee, that data is sent to remote host, it + * must call pxe_flush(). It forces sending of any data, that must be + * sent. + */ + if (pxe_flush(socket) == -1) { + /* failed to flush socket */ + pxe_close(socket); + return (0); + } + + /* perform reading cycle */ + + while (count < maxsize) { + /* pxe_recv() is similar to recv() call for common sockets, + * but have no flags parameter + */ + result = pxe_recv(socket, &data[count], maxsize - count); + + if (result == -1) { /* failed to recv */ + break; + } + + if (result == 0) /* nothing received yet */ + continue; + + count += result; + } + + pxe_close(socket); + + + /* End of example */ + + +3.3 Quick Reference to API, available for user code +---------------------------------------------------- + + This overview covers functions and macro definitions that + may be usefull for user code. + + +3.3.1 pxe_arp module +--------------------- + + This module is used mainly by internal code while sending IP + packets. + +macro definitions: + +MAX_ARP_ENTRIES - how much may be ARP table in size. If ARP table full + and new MAC must be placed, then one of older entry is + replaced by new. Default number is 4. + +PXE_MAX_ARP_TRY - how much trys will be peformed when sending ARP + requests, before say MAC search failed. Default: 3 + +PXE_TIME_TO_DIE - how much time to wait ARP reply in milliseconds. + Default: 5000 ms. + +PXE_ARP_SNIFF - sometimes it's usefull to get senders MACs from + incoming requests (this may save time, MAC may be found + in table without requesting it by ARP module itself). + But if network is big enough - ARP table will be + updated too often. By default this option is defined. + + +functions: + +void pxe_arp_init() + - inits pxe_arp module. Usually this call is performed from + pxe_core_init() + +const MAC_ADDR *pxe_arp_ip4mac(const PXE_IPADDR *addr) + - returns MAC address for requested IP address + +void pxe_arp_stats() + - shows ARP table. Available if defined PXE_MORE macro. + + +3.3.2 pxe_await module +----------------------- + + Implements awaiting mechanism. Many operations are performed + similar in protocol implementations. Usually, packet is sended and + application awaits for reply. pxe_await() function helps to simplify + code in such case. + It starts await callback function with some flags and counts + timeouts, try count. + + Here is example of awaiting: + + /* we start awaiting, with dns_await() calllback function, maximum 4 + * trys, each try 20 seconds and waiting data static_wait_data. + * Waiting data - is some data associated with current awaiting, it's + * used by await callback function. + */ + if (!pxe_await(dns_await, 4, 20000, &static_wait_data)) + return (NULL); + + /* pxe_await() returns 1 if awaiting was successfull (await function + * returned PXE_AWAIT_COMPLETED flag) + */ + + /* it's an awaiting function. pxe_await() provides current function, + * current try number, time exceeded from start of try, pointer to + * associated wait data. + */ + int + dns_await(uint8_t function, uint16_t try_number, uint32_t timeout, + void *data) + { + /* cast to our type of wait data */ + PXE_DNS_WAIT_DATA *wait_data = (PXE_DNS_WAIT_DATA *)data; + + switch(function) { + + case PXE_AWAIT_STARTTRY: + /* is called at start of each try + * Here must be performed any await initialisation + * (e.g. request packet sending ) + */ + if (!dns_request(wait_data)) { + /* if initialisation of try failed, try more */ + return (PXE_AWAIT_NEXTTRY); + } + /* otherwise return success result of await function */ + break; + + case PXE_AWAIT_FINISHTRY: + /* this function is called at the end of any try (even + * if try was successful). Here cleanup must be + * performed. + */ + if (wait_data->socket != -1) + pxe_close(wait_data->socket); + + wait_data->id += 1; + break; + + case PXE_AWAIT_NEWPACKETS: + /* while waiting this function called if new packets + * were received by pxe_core_recv_packets(). Actually + * it may be not packets we are waiting for, may be + * even not packets with out protocol. Here we must + * check for new usefull for us packets, receive + * new data if any. + */ + size = pxe_recv(wait_data->socket, wait_data->data, + wait_data->size); + + parse_dns_reply(wait_data); + + if (wait_data->result.ip != 0) { + /* return success of awaiting. This may be + * returned from any function + */ + return (PXE_AWAIT_COMPLETED); + } + + /* if await was not completed, continue waiting */ + return (PXE_AWAIT_CONTINUE); + break; + + case PXE_AWAIT_END: + /* this called if await is ended without any result */ + default: + break; + } + + return (PXE_AWAIT_OK); + } + + /* end of example */ + + So, wait data used for providing and receiving data while + awaiting. pxe_await() performs unified working with code, needed for + waiting of incoming packets. + +macro definitions: + +TIME_DELTA_MS - delay between iterations during awaitng. At each + iteration are checked: + * receiving of new packet. If received - awaiting + function with PXE_AWAIT_NEWPACKETS function is called. + * try timeout. if timeout exceeds maximum timeout - + awaiting function with PXE_AWAIT_FINISHTRY and + PXE_AWAIT_STARTTRY flags sequentially are called. + * try count. if try count exceeds maximum - awaiting + function with PXE_AWAIT_ENDED flag is called. This + means that await failed. + Default: 1 + +TIME_DELTA - default: 1000, same as TIME_DELTA_MS, but in ticks + for delay. + + +3.3.3 pxe_buffer module +------------------------ + + This module provides reading and writing of cyclic buffers. + It's not used directly by user code. + +macro definitions: + +PXE_POOL_SLOTS - if defined, then statical allocation of buffers is + used. Otherwise buffers are allocated at run-time from + heap with pxe_alloc() function. Current statical + allocation algorithm is simple and square, there are + two big buffers data storages divided in slots (by + default 2). + Each slot has size equal to + PXE_DEFAULT_RECV_BUFSIZE or PXE_DEFAULT_SEND_BUFSIZE. + Depending on requested size in pxe_buffer_alloc() + function data allocated from one of stoarge and + related slot marked busy. When pxe_buffer_free() called, + slot marked as free. + Default: undefined + +PXE_DEFAULT_RECV_BUFSIZE - size of receiving buffer. Default: 16392 + +PXE_DEFAULT_SEND_BUFSIZE - size of sending buffer. Default: 4096 + + +3.3.4 pxe_connection module +---------------------------- + + This module is one of TCP related modules. It implements + connection entity. TCP connection is logical structure, that have + needed by TCP protocol counters and states. + User code is not directly works with this module. + +macro definitions: + +PXE_MAX_TCP_CONNECTIONS - how much simultaneous connections may be. + + +functions: + +void pxe_connection_stats() + - returns connections statistics. Available if PXE_MORE macro is + defined. + + +3.3.5 pxe_core module +---------------------- + + This module performs lowlevel work with PXE API: initialisation, + receiving/sending of packets, provides information functions. + In most cases, user code doesn't uses this module directly. + +macro definitions: + +PXE_BUFFER_SIZE - size of core buffers, used in PXE API calling, + Default: 4096 + +PXE_CORE_STATIC_BUFFERS - if defined, core buffers are allocated statically. + Otherwise they are allocated in heap. Default: defined + +functions: + +int pxe_core_recv_packets() + - recieves all packets waiting in incoming queue of NIC, and calls + appropriate protocols if needed + + +void pxe_core_register(uint8_t ip_proto, pxe_protocol_call proc) + - registers IP stack protocol, associates protocol number and handler. + +const MAC_ADDR *pxe_get_mymac() + - returns MAC of NIC, for which PXE API is used. + +const PXE_IPADDR *pxe_get_ip(uint8_t id) + - returns of stored IP, for provided id. + id may be: + PXE_IP_MY - NIC IP address + PXE_IP_NET - network adrress + PXE_IP_NETMASK - network mask + PXE_IP_NAMESERVER - nameserver to use in name resolving + PXE_IP_GATEWAY - default gateway + PXE_IP_BROADCAST - broadcast address + PXE_IP_SERVER - server from which loading of pxeboot + was performed + PXE_IP_WWW - IP address of http-server + PXE_IP_ROOT - IP adddress of server, where root + file system is situated. Currently + it's synonym for PXE_IP_WWW + +void pxe_set_ip(uint8_t id, const PXE_IPADDR *ip) + - sets value by it's id. + +time_t pxe_get_secs() + - returns time in seconds. Used in timeout and resend checking. + +types: + +typedef int (*pxe_protocol_call)(PXE_PACKET *pack, uint8_t function) + - protocol callback function type + + +3.3.6. pxe_dhcp module +----------------------- + + This module implements simple DHCP client, used to obtain + gateway, nameserver and other information. + + +macro definitions: + +PXE_BOOTP_USE_LIBSTAND - use bootp() function provided by libstand instead + of own DHCP client. NOTE: bootp() doesn't set nameip (nameserver ip + structure), thus DNS resolving will be impossible. Default: undefined + + NOTE: to use bootp(), also UDP_DEFAULT_SOCKET macro must be defined. + + +functions: + +void pxe_dhcp_query(uint32_t xid) + - sends DHCPDISCOVER packet and sets core_ips, if gets reply. + + +3.3.6. pxe_dns module +---------------------- + + This module provides domain name resolving. Actually + A and CNAME resource records are supported. + +macro definitions: + +PXE_MAX_DNS_TIMEOUT - max time to wait DNS reply in milliseconds. + Default: 10 seconds + +PXE_MAX_DNS_TRYS - how many times to try to resend request, + if there is no reply. Default: 3 + +PXE_DNS_MAX_PACKET_SIZE - maximum UDP packet size in bytes. Default: 512. + This DNS client doesn't support TCP for resolving. + +functions: + +const PXE_IPADDR *pxe_gethostbyname(char *name) + - returns IP, if resolved, for provided domain name. + +uint32_t pxe_convert_ipstr(char *str) + - converts string value of ipv4 to uint32_t value. + + +3.3.8. pxe_filter module +------------------------- + + This module is not supposed to be used by user code directly. + It implements filtering of incoming IP packets. It's used by UDP and + TCP modules for sorting packets in appropriate socket. + Module provides functions for adding and removing filters. + Each filter contains source/destination ip:port definition and masks + for all of them. Usage of masks gives opportunity to recieve data + from subnet, or subset of ports. + +functions: + +void pxe_filter_init() + - inits filter module structures such as list of free filter entries. + +void pxe_filter_stats() + - show active filters information. Used for debugging. Available if + PXE_MORE macro defined. + + +3.3.9. pxe_http module +----------------------- + + pxe_http implements functions for getting files via HTTP. + Most of it's functions are used only by httpfs module. + At opening file pxe_exists() function is called, which + gets filesize (if possible) by HEAD method of request and opens + connection to file. Result of pxe_exists() call is keep-alive + connection to file. + pxe_get() function gets needed data and reestablishes + connection if needed. + if PXE_MORE defined - pxe_get_close() function becomes + available. It opens connection, gets portion of data and closes + connection. It's rather not optimal usage of http connections, + but some times it may be needed (e.g. for servers, where keep + alive connections are prohibited). + +macro definitions: + +PXE_MAX_HTTP_HDRLEN - buffer size for generating/getting http header. + Default: 1024 bytes. + +functions: + +int pxe_fetch(char *server, char *filename, off_t from, size_t size) + - testing function, gets file from server ()may be partially) and + outputs received data to screen. Available if PXE_MORE defined. + + +3.3.10. httpfs module +---------------------- + + httpfs is filesystem, available via HTTP. It is read-only + filesystem, mainly with sequential access to files. It exports + file operations structure and is not used directly by user code. + httpfs module may support some kind of caching: it requests + more data per request then it's needed at http_read() call and + reads this data later. Such approach speed ups connections speed + and reduces server load. + This opportunity is available if PXE_HTTPFS_CACHING macro + is defined. + + +3.3.11. pxe_icmp module +------------------------ + + pxe_icmp module provides some basic functionality of ICMP + protocol: echo requesting/replying. + Module is unavailable, if PXE_MORE undefined. + + +macro definitions: + +PXE_ICMP_TIMEOUT - timeout in milliseconds when waiting echo reply. + Default: 5000 ms. + + +functions: + +int pxe_ping(const PXE_IPADDR *ip, int count, int flags) + - works similar to usual ping, sends echo request and shows timeout + before echo reply. + +int pxe_icmp_init() + - inits module + + +3.3.12. pxe_ip module +---------------------- + + This module implemets IP protocol functions, also it works + with routing table. It also declares PXE_IPADDR, that is used widely. + +macro definitions: + +PXE_MAX_ROUTES - route table size. Default: 4, usually used 2 entries. + + +functions: + +uint16_t pxe_ip_checksum(const void *data, size_t size) + - calculates checksum for provided block of data. + + +void pxe_ip_route_init(const PXE_IPADDR *def_gw) + - inits routing table, sets default gateway + + +int pxe_ip_route_add(const PXE_IPADDR *net, uint32_t mask, + const PXE_IPADDR *gw) + - adds route to routing table + +int pxe_ip_route_del(const PXE_IPADDR *net, uint32_t mask, + const PXE_IPADDR *gw) + - dels route from routing table + +uint32_t pxe_ip_get_netmask(const PXE_IPADDR *ip) + - returns class based netmask for ip. + +int pxe_ip_route_default(const PXE_IPADDR *gw) + - adds default gateway + +int pxe_ip_send(void *data, const PXE_IPADDR *dst, uint8_t protocol, + uint16_t size) + - sends ip packet with provided data. There must be space for + IP header in buffer, pointed by data. + +void pxe_ip_route_stat() + - show route table. Available if PXE_MORE defined + + +3.3.13. pxe_isr module +----------------------- + + Contains assembler side functions, used in pxe_core. + User code has no direct access to them. + There supported: installation/removing of interrupt handler, + interrupt handler and wrapper for PXE API calls. + + +3.3.14. pxe_mem module +----------------------- + + Actually this module just a wrapper to bcopy(), alloc() and free() + functions. That's done to make pxe_http library more portable. + But in fact, pxe_http depends much on other libstand functions, + such as printf(), strcpy() and etc. So this module is not very usefull and + will be probably removed in future. + + +3.3.15. pxe_sock module +------------------------ + + Most used by user code module. Contains implementation of + pxe_http sockets API. + + +macro definitions: + +PXE_DEFAULT_SOCKETS - count of sockets used at the same time. If all + socket structures are used, next socket creating calls + and API that depends on it, will fail. Default: 4 + + +PXE_SOCKET_TIMEOUT - how long pxe_recv() will be wiating incoming data per + call before return error. Default: 30000 ms + +PXE_SOCKET_CHECK_TIMEOUT - If pxe_recv() waits incoming data and have big free + space in buffer, and in case of TCP protocol it may notice + remote server about this by sending empty packet (with + no data) acking current state, so remote host updates + knowledge about receiving window of client and sends new + data. *** DIFF OUTPUT TRUNCATED AT 1000 LINES ***
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201301251151.r0PBpTHE056739>