KITL Overview: Packet layout
Posted by: Upender Sandadi
Overview of KITL
KITL, which stands for Kernel Independent Transport Layer, is the basic debugging protocol used for debugging Windows CE devices. The KITL layer on the desktop and device manage both the transport and stream abstraction from applications. As part of this abstraction, KITL provides:
-- Transport initialization
-- Stream connect/disconnects
-- Stream packet sequencing
-- Managing packet loss using re-transmission logic
-- Providing common API sets for applications to interact with streams.
In this entry, we will look at a KITL packet and understand the different components which make up both KITL data and administrative packets. This information will form groundwork for future blog entries on KITL protocol and troubleshooting tips.
KITL Packet
All KITL packets have the following form: Header + Data. Header defines the packet type and data is a custom data block depending on the packet type. If you break up a KITL header, it has the following components:
Protocol Identifier
Always given by string: EDBG (45 44 42 47).
Stream Identifier
This is a byte which is assigned to each unique KITL stream. There are four pre-defined default streams and rest of the slots can be used by applications.
0x0: Debug messages
0x1: Target control / relfsd packets
0x2: Kernel debugger
0xff: Administrative stream used for protocol management
0x3-0xfe: custom streams which can be used by applications
This stream identifier is returned from KITL layer to the application when a stream is registered using KITLRegisterClient API call. Applications should use this ID when calling KITLSend and KITLRecv to send/recv packets to/from a particular stream.
Packet Type
This is a byte which defines the packet type. It can be one or more of the following values:
0x1: This is set if the message is from the device
0x2: This is set if the frame is a NACK
0x4: This is set if the frame is a ACK
0x8: This is set to reset sequence numbers to 0
0x10: This is set when responding to KITL administrative messages.
Packet Sequence Number
This is a byte which defines a rolling packet sequence numbers between 0 and 255. Once packet sequence number 255 is sent, then the next packet will start at sequence number 0. Both desktop and device have their unique sequence numbers. This is to allow asymmetric data transfers where one side of the protocol could send more data packets compared to the other.
Data Command
This could be one of the following values. The actual KITL data starts at the end of the header and amount and nature of the data packet depends on the command listed here.
0-4: unused currently (0x2 is used as a ‘jump to image’ packet but that gets processed by the bootloader and not KITL on device so we will not discuss that here).
0x5: Device Reset
0x6: Service Configuration
0x7: Service Data
0x8: Kernel Debug Break
0x9: Transport Configuration
0xA: Timer Packet
Now let us look at some sample KITL Packets and see how we can interpret them with this information. These packets were captured using netmon (one can also use any software which can capture network traffic when using Ethernet KITL transport).
1) KITL Transport configuration packet (sent from device when KITL starts up): This is the first packet which is sent by the device when KITL starts up. It is sent to a particular port (981) and to broadcast address within a subnet. Any Platform Builder session which is actively listening for this device would respond back with a host configuration message and after this desktop and device will open a dedicated KITL channel. Further communication between the desktop and device happens on this custom channel. Shown below (in green) is the transport configuration packet sent by device to port 981 and broadcast IP address. For Ethernet transport included in this packet are the device name (CEPC37480 in this example), device IP address (0x9D.0x38.0xB2.0x12 in this example), and device UDP port (0x3D5 in this example). Desktop uses this information to open a custom channel with the device.
00000020 45 44 42 47 FF 00 EDBG..
00000030 00 09 20 00 30 00 43 45 50 43 33 37 34 38 30 00 ....0.CEPC37480.
00000040 00 00 00 00 00 00 9D 38 B2 12 00 11 95 28 92 68 .......8.....(.h
00000050 03 D5 ..
2) KITL Service configuration packet (sent from both desktop and device): This packet is sent when a service (KITL stream) is starting up. Both desktop and device have to acknowledge the service configuration packets from the other side at which point the stream state is set to be connected. Here is a service configuration packet for DBGMSG service from device. KITL header is shown in green and rest is the configuration data. This is an administrative packet (0xFF after the protocol identifier) from device (0x01) with sequence number 0x00 (since the stream is not connected yet) and packet command is 0x06 (service configuration).
00000020 45 44 42 47 FF 01 EDBG..
00000030 00 06 01 44 42 47 4D 53 47 00 33 37 34 38 30 00 ...DBGMSG.37480.
00000040 00 00 00 00 00 00 9D 00 10 00 ..........
3) Service Configuration acknowledgement: Here is an acknowledgement packet for a service configuration packet. Again the header is in green. The only significant part here is the packet type which is set to 0x10 (response to administrative packet). Rest is almost same as a service configuration data packet. This packet is sent from desktop to device. Once device receives this packet, then the DBGMSG stream’s state on device is set to be connected. At that point any applications on the device can start sending debug messages to the desktop. Note that the stream is fully connected only if desktop also sends a similar configuration packet (as in step (2) above) and gets an acknowledgement from device.
00000020 45 44 42 47 FF 10 EDBG..
00000030 00 06 01 44 42 47 4D 53 47 00 B8 A9 FF 02 A0 F9 ...DBGMSG.......
00000040 FF 02 18 6A 4A 45 02 FF 00 00 ...jJE....
4) KITL Data packet (this is a RELFSD packet from device): KITL header is highlighted in green. Rest of the packet is data for the relfsd stream to interpret. In this case, stream ID is 0x01 (which is set immediately after the protocol identifier) and type is set to 0x01 meaning this is a packet from device. Also the sequence number is 0xA4 and packet command is 0x07 which means it is a service data packet. This packet happens to be the KITL packet sent from shell.exe on device to desktop to see if there is any command to run on the device.
00000020 45 44 42 47 01 01 EDBG..
00000030 A4 07 AA 55 55 AA 04 00 0D 00 FE FF FF FF 01 00 ...UU...........
00000040 00 00 F2 5A A5 0A 1A ...Z...
5) KITL ACK packet (from desktop to device): Here the packet stream identifier is set to 0x01, type is set to acknowledgement (0x04), packet sequence we are acknowledging is 0xA4 and 0x07 is packet data command. If the acknowledgement was from device to desktop then packet type would be set to 0x5 (0x4 for acknowledgement OR with 0x1 for a packet originating from device).
00000020 45 44 42 47 01 04 EDBG..
00000030 A4 07 00 00 00 00 00 00 00 00 00 00 ............
6) KITL Administrative timer packet (sent approximately every two seconds from desktop to device): When device is stopped in kernel debugger, time on the device doesn’t advance. As a result any time related opeations (including KITL timer logic) will not work. In those cases, we use this packet as a marker to re-transmit any lost packets to the desktop. There is no custom data associated with this packet.
00000020 45 44 42 47 FF 00 EDBG..
00000030 00 0A 00 00 00 00 00 00 00 00 00 00 ............
-----------------
Upender R. Sandadi