Enabling KITL

Article
06/30/2006

The KITL version of the OS image is placed in the release directory when the IMGNOKITL flag is not set, and the non-KITL image is released when IMGNOKITL is set to 1. KITL functionality can be included in both debug and retail devices, depending on your needs. It can also be configured to start on boot, called active KITL, or to start the first time a service on the device registers with KITL, called passive KITL. Passive KITL works with KITL in an inactive state until it is required. Passive KITL does not affect the overall performance of the device. For more information, see Active and Passive KITL.

The KITLTRANSPORT structure defines a KITL transport, which provides all the KITL functionality. KITL needs to communicate with the underlining hardware including the ability to encode and decode a packet, send and receive a frame or packet, enable and disable the transport interrupt, and get and set configuration information. The following table shows the functions you need to implement to support this functionality.

Function	Description
TransportEncode	Makes a transport ready packet that KITL can later send from the transport through TransportSend. The implementation frames the data with transport specific and checksum information. Using an Ethernet transport, TransportEncode frames the packet with a User Datagram Protocol (UDP) header.
TransportDecode	Called when KITL receives a raw packet from the transport through TransportRecv to extract the data field of the packet. Using an Ethernet transport, TransportDecode will validate the packet, checksum, and return the pointer immediately after the UDP header.
TransportSend	Called to send a raw packet, framed by TransportEncode, from the transport. KITL guarantees exclusive access to the transport when TransportSend is called. Using an Ethernet transport, TransportSend will program the hardware and place the packet on the Ethernet.
TransportRecv	Called to receive a raw packet from the transport. KITL guarantees exclusive access to the transport when TransportRecv is called. Using an Ethernet transport TransportRecv will read from the Ethernet hardware.
TransportEnableInt	Called to enable or disable transport interrupt.
TransportGetDevCfg	Called to provide device information to the debug host with the transport defining how the data appears. KITL handles the data as an opaque entity and sends it to the debug host. TransportGetDevCfg is only called at the initial handshake with the debug host. Using an Ethernet transport, the information usually includes IP address, MAC address, and port number.
TransportSetHostCfg	Called when KITL receives the transport information of the debug host with the transport defining how the data appears. KITL handles the data as an opaque entity and TransportSetHostCfg can use the information to setup the transport. TransportSetHostCfg is only called at the initial handshake with the debug host.

KITL is initialized by calling KitlInit typically during the OEMInit phase of the boot process. KitlInit must be called before any debug services can be started. As part of the KitlInit processing, the kernel calls the OEMKitlInit function to perform hardware initialization.

KitlInit may be called any time after the KernelStart function has been called, typically as part of OEMInitDebugSerial or OEMInit processing. KitlInit should also be called in the resume from suspend processing in OEMPowerOff. The parameter fStartKitl tells the kernel if it should start the interrupt service thread (IST) at the time of call. If fStartKitl is FALSE, KITL behaves in a passive mode, waiting dormant until KITLRegisterClient is called. This technique is used on test devices that require the use of just-in-time (JIT) debugging. If fStartKitl is TRUE, KITL will start communicating with the desktop and will block until a connection is made. Also, when fStartKitl is set to TRUE the default services PPSH, DBGMSG, and KDBG are started based on the configuration settings from the desktop. Because KITL is used to attach all full-function debugging tools, if an error occurs during KITL initialization, use KITLOutputDebugString to output debug messages. KITLOutputDebugString eventually uses an OEM supplied function in the OAL for debug messages. The kernel then calls the OEM's routine.

Once KITL is up and running, it is in a waiting state, waiting for data to be received by the transport and waiting for device side services to send data out. The typical call sequence is shown in the following code example.

RecvData ()
{
   LockTransport ();
   Result = KITL. TransportRecv (pData, pcbShort);
   UnlockTransport ();
   If (Result) {
pData = KITL.TransportDecode (pData, pcbShort);
   }
}

When the KITL protocol has data to send, it passes a buffer to the TransportEncode function that has space allocated for the header and trailer. TransportEncode adds the header and trailer to the frame and passes the encapsulated data back to the kernel. The kernel then calls TransportSend to send out the data to the desktop side, as shown in the following code sample.

SendData (...)
{
   if (KITL.TransportEncode (pData, cbShort)) {
   // pData has room for Hdr/Tlr allocated
      LockTransport ();
      KITL.TransportSend (pData, cbShort + KITL.FrmHdrSize + KITL.FrmTlrSize);
      UnlockTransport ();
      }
}

If your KITL transport requires a timer, the KITL protocol supports a 1 second resolution timer. The timer requires a call to KitlSetTimerCallback. The timer is a not a periodic timer and is only called once every nSecs seconds. If you need the timer to be called periodically, you can call KitlSetTimerCallback again when the timer expires. You can also request more than one timer.

When the timer is no longer needed, call KitlStopTimerCallback to stop the timer.

Share via

Enabling KITL

See Also

Additional resources