Overview of KITL

KITL, which stands for KernelIndependent Transport Layer, is the basic debugging protocol used for debuggingWindows CE devices. The KITL layer on the desktop and device manage both thetransport and stream abstraction from applications. As part of thisabstraction, KITL provides:

-- Transport initialization

-- Stream connect/disconnects

-- Stream packet sequencing

-- Managing packet loss usingre-transmission logic

-- Providing common API setsfor applications to interact with streams.

In this entry, we will lookat a KITL packet and understand the different components which make up bothKITL data and administrative packets. This information will form groundwork forfuture blog entries on KITL protocol and troubleshooting tips.

KITL Packet

All KITL packets have thefollowing form: Header + Data. Header defines the packet type and data is acustom data block depending on the packet type. If you break up a KITL header,it has the following components:

ProtocolIdentifier

Always given by string: EDBG (45 44 42 47).

StreamIdentifier

This is a byte which isassigned to each unique KITL stream. There are four pre-defined default streamsand rest of the slots can be used by applications.

0x0: Debug messages

0x1: Target control / relfsdpackets

0x2: Kernel debugger

0xff: Administrative stream usedfor protocol management

0x3-0xfe: custom streams which can beused by applications

This stream identifier isreturned from KITL layer to the application when a stream is registered usingKITLRegisterClient API call. Applications should use this ID when callingKITLSend and KITLRecv to send/recv packets to/from a particular stream.

Packet Type

This is a byte which definesthe packet type. It can be one or more of the following values:

0x1: This is set if the messageis from the device

0x2: This is set if the frame isa NACK

0x4: This is set if the frame isa ACK

0x8: This is set to resetsequence numbers to 0

0x10: This is set when respondingto KITL administrative messages.

PacketSequence Number

This is a byte which definesa rolling packet sequence numbers between 0 and 255. Once packet sequencenumber 255 is sent, then the next packet will start at sequence number 0. Bothdesktop and device have their unique sequence numbers. This is to allowasymmetric data transfers where one side of the protocol could send more datapackets compared to the other.

DataCommand

This could be one of thefollowing values. The actual KITL data starts at the end of the header andamount and nature of the data packet depends on the command listed here.

0-4: unused currently (0x2 isused as a ‘jump to image’ packet but that gets processed by the bootloader andnot 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 somesample KITL Packets and see how we can interpret them with this information.These packets were captured using netmon (one can also use any software whichcan capture network traffic when using Ethernet KITL transport).

1) KITL Transportconfiguration packet (sent from device when KITL starts up): This is the firstpacket which is sent by the device when KITL starts up. It is sent to aparticular port (981) and to broadcast address within a subnet. Any PlatformBuilder session which is actively listening for this device would respond back witha host configuration message and after this desktop and device will open adedicated KITL channel. Further communication between the desktop and devicehappens on this custom channel. Shown below (in green) is the transportconfiguration packet sent by device to port 981 and broadcast IP address. ForEthernet transport included in this packet are the device name (CEPC37480 inthis example), device IP address (0x9D.0x38.0xB2.0x12 in this example), anddevice UDP port (0x3D5 in this example). Desktop uses this information to opena custom channel with the device.

0000002045 44 42 47 FF00EDBG..

0000003000 09 20 00 30 00 43 45 50 43 3337 34 38 30 00 ....0.CEPC37480.

0000004000 00 00 00 00 00 9D 38 B2 12 00 11 95 28 9268 .......8.....(.h

0000005003 D5..

2) KITL Service configurationpacket (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 theservice configuration packets from the other side at which point the streamstate is set to be connected. Here is a service configuration packet for DBGMSGservice from device. KITL header is shown in green and rest is theconfiguration data. This is an administrative packet (0xFF after the protocolidentifier) from device (0x01) with sequence number 0x00 (since the stream isnot connected yet) and packet command is 0x06 (service configuration).

0000002045 44 42 47 FF 01EDBG..

0000003000 06 01 44 42 47 4D 53 47 00 3337 34 38 30 00 ...DBGMSG.37480.

0000004000 00 00 00 00 00 9D 00 10 00..........

3) Service Configurationacknowledgement: Here is an acknowledgement packet for a service configurationpacket. Again the header is in green. The only significant part here is thepacket type which is set to 0x10 (response to administrative packet). Rest isalmost same as a service configuration data packet. This packet is sent fromdesktop to device. Once device receives this packet, then the DBGMSG stream’sstate on device is set to be connected. At that point any applications on thedevice can start sending debug messages to the desktop. Note that the stream isfully connected only if desktop also sends a similar configuration packet (asin step (2) above) and gets an acknowledgement from device.

0000002045 44 42 47 FF10EDBG..

0000003000 06 01 44 42 47 4D 53 47 00 B8A9 FF 02 A0 F9 ...DBGMSG.......

00000040FF 02 18 6A 4A 45 02 FF 00 00...jJE....

4) KITL Data packet (this isa RELFSD packet from device): KITL header is highlighted in green. Rest of thepacket is data for the relfsd stream to interpret. In this case, stream ID is0x01 (which is set immediately after the protocol identifier) and type is setto 0x01 meaning this is a packet from device. Also the sequence number is 0xA4and packet command is 0x07 which means it is a service data packet. This packethappens to be the KITL packet sent from shell.exe on device to desktop to seeif there is any command to run on the device.

0000002045 44 42 47 0101EDBG..

00000030A4 07 AA 55 55 AA 04 00 0D 00 FEFF FF FF 01 00 ...UU...........

0000004000 00 F2 5A A5 0A 1A...Z...

5) KITL ACK packet (fromdesktop to device): Here the packet stream identifier is set to 0x01, type isset to acknowledgement (0x04), packet sequence we are acknowledging is 0xA4 and0x07 is packet data command. If the acknowledgement was from device to desktopthen packet type would be set to 0x5 (0x4 for acknowledgement OR with 0x1 for apacket originating from device).

0000002045 44 42 47 0104EDBG..

00000030A4 07 00 00 00 00 00 00 00 00 0000............

6) KITL Administrative timerpacket (sent approximately every two seconds from desktop to device): When deviceis stopped in kernel debugger, time on the device doesn’t advance. As a resultany time related opeations (including KITL timer logic) will not work. In thosecases, we use this packet as a marker to re-transmit any lost packets to thedesktop. There is no custom data associated with this packet.

0000002045 44 42 47 FF00EDBG..

0000003000 0A 00 00 00 00 00 00 00 00 0000............

-----------------