diff options
Diffstat (limited to 'bsps/powerpc/psim/net/README')
| -rw-r--r-- | bsps/powerpc/psim/net/README | 141 |
1 files changed, 141 insertions, 0 deletions
diff --git a/bsps/powerpc/psim/net/README b/bsps/powerpc/psim/net/README new file mode 100644 index 0000000000..4ca287788c --- /dev/null +++ b/bsps/powerpc/psim/net/README @@ -0,0 +1,141 @@ +PSIM NETWORKING HOWTO +===================== + +IMPLEMENTATION INFORMATION + +1) NIC hardware emulation. + + In order to simulate networking the simulator (PSIM in our case) + has to emulate some networking hardware. + At the time of this writing (2009/09 - gdb-6.8) no such emulation + is available. + However, a patch has been created which adds this functionality + to PSIM (see diff in this directory). Unfortunately, implementing + a network chip (or some other sort of 'data-source') in PSIM is + not quite that simple since PSIM is at the end of the day a single- + threaded, monolithic application which has no built-in support for + external asynchronous events (e.g., NIC packet reception or a + character arriving at a UART [the PSIM BSP uses a polled console + driver]). + In order to add such asynchronous support, the 'async_io' module + was added to PSIM. 'async_io' uses OS-support in the form of + a signal (SIGIO) that the OS sends to the PSIM process when I/O + becomes possible. The signal handler then executes a callback + which e.g., may schedule a PSIM interrupt. + However, the use of SIGIO and the O_ASYNC fcntl-flag is not portable + (BSD and linux only). + The 'ethtap' NIC emulation uses another not quite portable OS + service -- the host OS' TUN/TAP device which is some sort of + pipe with a networking-interface on one end and a file-system + interface on the other. The 'ethtap' NIC reads/writes packets + to the file-system interface and they then become available + to the host OS' networking. + This ascii-art shows how a RTEMS application inside PSIM can + communicate with an application on the host with both using + sockets. (If the host sets up proper routing table entries + then the RTEMS APP can even communicate with the internet...) + + + RTEMS APP HOST APP + | | + ............. ............ + . <socket> . .<socket> . + .RTEMS BSD . . HOST OS . + .networking . .networking. + ............. ............ + + ....................... ..................... + .RTEMS BSD IF "ifsim1". . HOST OS IF: "tap0". + .e.g., 10.0.0.100 . . e.g., 10.0.0.1 . + ....................... ..................... + o + ............. o + .RTEMS ifsim. o + . driver . o + ............. o + || o + || o + --------------- o + ethtap o + hw emulation o + --------------- o + ^ o + | o + -----> /dev/net/tun (special file on host OS) ooo + + +2) Device-tree. Once PSIM supports the 'ethtap' device then it + must be added to the device tree. The following properties are + relevant (The register addresses must match with what the + BSP/if_sim expects): + + #### ETHTAP @ 0x0c100020 for 0x40 + # + + /ethtap@0x0c100020/reg 0x0c100020 0x40 + # route interrupt to open-pic + /ethtap@0x0c100020 > 0 irq0 /opic@0x0c130000 + # 'tun' device on host + /ethtap@0x0c100020/tun-device "/dev/net/tun" + # name of 'tap' device to use + /ethtap@0x0c100020/tap-ifname "tap0" + # ethernet address of simulated IF + /ethtap@0x0c100020/hw-address "00:00:00:22:11:00" + # generate CRC and append to received packet before + # handing over to the simulation. This is mostly for + # debugging the rtems device driver. If unsure, leave 'false'. + /ethtap@0x0c100020/enable-crc false + + The 'tun-device' and 'tap-ifname' properties allow you to + configure the name of the special-file and the 'tap' interface + on the host. + +3) RTEMS driver. The 'if_sim' driver implements a driver for + the 'ethtap' device. + +USAGE INFORMATION + +1) Configure application for networking; the + RTEMS_BSP_NETWORK_DRIVER_NAME is "ifsim1" + and + RTEMS_BSP_NETWORK_DRIVER_ATTACH is rtems_ifsim_attach + +2) Patch, configure (--target=powerpc-rtems) and build + gdb-6.8. As already mentioned, the NIC emulation only + is available if your host-os is linux. + +3) Create a 'device-tree' file. The BSP build process produces + a shell-script 'psim' residing in + + <bsp_installdir>/powerpc-rtems/psim/tests/ + + which can be used for generating a device-tree file. + + Call 'psim -d -n <application>'. The '-n' option adds the + emulated interface (the lines above) to the device tree. + The resulting file is saved as <application>.device. + + The 'psim' script can also be used to launch an application + directly -- just omit the '-d' option. + +4) Linux host network configuration: + Create a 'permanent' 'tap' interface. This allows you + to use 'psim' w/o special privileges (the 'tunctl' command + still must be executed by the super-user). + + sudo tunctl -u <uid-of-user-running-psim> + + You now can configure the 'tap0' interface: + + sudo ifconfig tap0 10.0.0.1 up + + and e.g., run a BOOTP server to provide RTEMS with its + network configuration: + + sudo dhcpd3 -d tap0 + + Assuming that BOOTP gives the RTEMS guest an IP address + e.g., '10.0.0.100' you can 'ping' the RTEMS guest + from the linux host: + + ping 10.0.0.100 |