* Memory Support::      Memory support.* Misc Support::        Other needed functions.* Debugging::            Useful Debugging Functions@end menu@node I/O Support, Memory Support, , Libc@subsection Making I/O work@node Memory Support, Misc Support, I/O Support, Libc@subsection Routines for dynamic memory allocationTo support using any of the memory functions, you need to implementsbrk(). @code{malloc()}, @code{calloc()}, and @code{realloc()} all call@code{sbrk()} at there lowest level. @code{caddr_t} is defined elsewhereas @code{char *}. @code{RAMSIZE} is presently a compile time option. Allthis does is move a pointer to heap memory and check for the upperlimit. @ref{glue.c,,Example libc support code}. @code{sbrk()} returns apointer to the previous value before more memory was allocated.@smallexample/* _end is set in the linker command file *extern caddr_t _end;//* just in case, most boards have at least some memory */#ifndef RAMSIZE#  define RAMSIZE             (caddr_t)0x100000#endif/* * sbrk -- changes heap size size. Get nbytes more *         RAM. We just increment a pointer in what's *         left of memory on the board. */caddr_tsbrk(nbytes)     int nbytes;@{  static caddr_t heap_ptr = NULL;  caddr_t        base;  if (heap_ptr == NULL) @{    heap_ptr = (caddr_t)&_end;  @}  if ((RAMSIZE - heap_ptr) >= 0) @{    base = heap_ptr;    heap_ptr += nbytes;    return (base);  @} else @{    errno = ENOMEM;    return ((caddr_t)-1);  @}@}@end smallexample@node Misc Support, Debugging, Memory Support, Libc@subsection Misc support routinesThese are called by @code{newlib} but don't apply to the embeddedenvironment. @code{isatty()} is self explanatory. @code{kill()} doesn'tapply either in an environment withno process control, so it justsexits, which is a similar enough behavior. @code{getpid()} can safelyreturn any value greater than 1. The value doesn't effect anything in@code{newlib} because once again there is no process control.@smallexample/* * isatty -- returns 1 if connected to a terminal device, *           returns 0 if not. Since we're hooked up to a *           serial port, we'll say yes and return a 1. */intisatty(fd)     int fd;@{  return (1);@}/* * getpid -- only one process, so just return 1. */#define __MYPID 1intgetpid()@{  return __MYPID;@}/* * kill -- go out via exit... */intkill(pid, sig)     int pid;     int sig;@{  if(pid == __MYPID)    _exit(sig);  return 0;@}@end smallexample@node Debugging, , Misc Support, Libc@subsection Useful debugging functionsThere are always a few useful functions for debugging your project inprogress. I typically implement a simple @code{print()} routine thatruns standalone in liblgoss, with no @code{newlib} support. The I/Ofunction @code{outbyte()} can also be used for low level debugging. Manytimes print will work when there are problems that cause @code{printf()} tocause an exception. @code{putnum()} is just to print out values in hexso they are easier to read.@smallexample/* * print -- do a raw print of a string */ intprint(ptr)char *ptr;@{  while (*ptr) @{    outbyte (*ptr++);  @}@}/* * putnum -- print a 32 bit number in hex */intputnum (num)unsigned int num;@{  char  buffer[9];  int   count;  char  *bufptr = buffer;  int   digit;    for (count = 7 ; count >= 0 ; count--) @{    digit = (num >> (count * 4)) & 0xf;        if (digit <= 9)      *bufptr++ = (char) ('0' + digit);    else      *bufptr++ = (char) ('a' - 10 + digit);  @}  *bufptr = (char) 0;  print (buffer);  return;@}@end smallexampleIf there are LEDs on the board, they can also be put to use fordebugging when the serial I/O code is being written. I usually implementa @code{zylons()} function, which strobes the LEDS (if there is morethan one) in sequence, creating a rotating effect. This is convenientbetween I/O to see if the target is still alive. Another useful LEDfunction is @code{led_putnum()}, which takes a digit and displays it asa bit pattern or number. These usually have to be written in assemblerfor each target board. Here are a number of C based routines that may beuseful.@code{led_putnum()} puts a number on a single digit segmentedLED display. This LED is set by setting a bit mask to an address, where1 turns the segment off, and 0 turns it on. There is also a littledecimal point on the LED display, so it gets the leftmost bit. The otherbits specify the segment location. The bits look like:@smallexample        [d.p | g | f | e | d | c | b | a ] is the byte.@end smallexampleThe locations are set up as:@smallexample              a           -----        f |     | b          |  g  |           -----          |     |        e |     | c           -----             d@end smallexampleThis takes a number that's already been converted to a string, andprints it. @smallexample#define LED_ADDR	0xd00003voidled_putnum ( num )char num;@{    static unsigned char *leds = (unsigned char *)LED_ADDR;    static unsigned char num_bits [18] = @{      0xff,						/* clear all */      0xc0, 0xf9, 0xa4, 0xb0, 0x99, 0x92, 0x82, 0xf8, 0x80, 0x98, /* numbers 0-9 */      0x98, 0x20, 0x3, 0x27, 0x21, 0x4, 0xe 		/* letters a-f */    @};    if (num >= '0' && num <= '9')      num = (num - '0') + 1;    if (num >= 'a' && num <= 'f')      num = (num - 'a') + 12;    if (num == ' ')      num = 0;    *leds = num_bits[num];@}/* * zylons -- draw a rotating pattern. NOTE: this function never returns. */voidzylons()@{  unsigned char *leds 	= (unsigned char *)LED_ADDR;  unsigned char curled = 0xfe;  while (1)    @{      *leds = curled;      curled = (curled >> 1) | (curled << 7);      delay ( 200 );    @}@}@end smallexample@node GDB, Binutils, Libraries, Top@chapter Writing a new GDB backendTypically, either the low-level I/O routines are used for debugging, orLEDs, if present. It is much easier to use GDb for debugging anapplication. There are several different techniques used to have GDB workremotely. Commonly more than one kind of GDB interface is used to cobera wide variety of development needs.The most common style of GDB backend is an exception handler forbreakpoints. This is also called a @emph{gdb stub}, and is requires thetwo additional lines of init code in your @code{main()} routine. The GDBstubs all use the GDB @emph{remote protocol}. When the application gets abreakpoint exception, it communicates to GDB on the host.Another common style of interfacing GDB to a target is by using anexisting ROM monitor. These break down into two main kinds, a similarprotocol to the GDB remote protocol, and an interface that uses the ROMmonitor directly. This kind has GDB simulating a human operator, and allGDB does is work as a command formatter and parser. @menu* GNU remote protocol::         The standard remote protocol.* Exception handler::           A linked in exception handler.* ROM monitors::                Using a ROM monitor as a backend.* Other remote protocols::      Adding support for new protocols.@end menu@node GNU remote protocol, Exception handler, ,GDB@section The standard remote protocolThe standard remote protocol is a simple, packet based scheme. A debugpacket whose contents are @emph{<data>} is encapsulated for transmissionin the form:@smallexample	$ <data> # CSUM1 CSUM2@end smallexample@emph{<data>} must be ASCII alphanumeric and cannot include characters@code{$} or @code{#}.  If @emph{<data>} starts with two charactersfollowed by @code{:}, then the existing stubs interpret this as asequence number. For example, the command @code{g} is used to read thevalues of the registers. So, a packet to do this would look like@smallexample        $g#67@end smallexample@emph{CSUM1} and @emph{CSUM2} are an ascii representation in hex of an8-bit checksum of @emph{<data>}, the most significant nibble is sent first.the hex digits 0-9,a-f are used.A simple protocol is used when communicating with the target. This ismainly to give a degree of error handling over the serial cable. Foreach packet transmitted successfully, the target responds with a@code{+} (@code{ACK}). If there was a transmission error, then the targetresponds with a @code{-} (@code{NAK}). An error is determined when thechecksum doesn't match the calculated checksum for that data record.Upon reciept of the @code{ACK}, @code{GDB} can then transmit the nextpacket. Here is a list of the main functions that need to be supported. Each datapacket is a command with a set number of bytes in the command packet.Most commands either return data, or respond with a @code{NAK}. Commandsthat don't return data respond with an @code{ACK}. All data values areascii hex digits. Every byte needs two hex digits to represent t. Thismeans that a byte with the value @samp{7} becomes @samp{07}. On a 32 bitmachine this works out to 8 characters per word. All of the bytes in aword are stored in the target byte order. When writing the host side ofthe GDB protocol, be careful of byte order, and make sure that the codewill run on both big and little endian hosts and produce the same answers.These functions are the minimum required to make a GDB backend work. Allother commands are optional, and not supported by all GDB backends.@table @samp@item  read registers  @code{g}returns @code{XXXXXXXX...}Registers are in the internal order for GDB, and the bytes in a registerare in the same order the machine uses. All values are in sequencestarting with register 0. All registers are listed in the same packet. Asample packet would look like @code{$g#}.@item	write registers	@code{GXXXXXXXX...}@code{XXXXXXXX} is the value to set the register to.  Registers are inthe internal order for GDB, and the bytes in a register are in the sameorder the machine uses. All values are in sequence starting withregister 0. All registers values are listed in the same packet. A samplepacket would look like @code{$G000000001111111122222222...#}returns @code{ACK} or @code{NAK}@item	read memory     @code{mAAAAAAAA,LLLL}@code{AAAAAAAA} is address, @code{LLLL} is length. A sample packet wouldlook like @code{$m00005556,0024#}. This would request 24 bytes startingat address @emph{00005556}returns @code{XXXXXXXX...}@code{XXXXXXXX} is the memory contents. Fewer bytes than requested willbe returned if only part of the data can be read. This can be determinedby counting the values till the end of packet @code{#} is seen andcomparing that with the total count of bytes that was requested.@item	write memory	@code{MAAAAAAAA,LLLL:XXXXXXXX}@code{AAAAAAAA} is the starting address, @code{LLLL} is the number ofbytes to be written, and @code{XXXXXXXX} is value to be written. Asample packet would look like@code{$M00005556,0024:101010101111111100000000...#}returns @code{ACK} or @code{NAK} for an error. @code{NAK} is alsoreturned when only part of the data is written.@item	continue	@code{cAAAAAAAAA}@code{AAAAAAAA} is address to resume execution at. If @code{AAAAAAAA} isomitted, resume at the curent address of the @code{pc} register.returns the same replay as @code{last signal}. There is no immediatereplay to @code{cont} until the next breakpoint is reached, and theprogram stops executing.@item	step		sAA..AA@code{AA..AA} is address to resumeIf @code{AA..AA} is omitted, resume at same address.returns the same replay as @code{last signal}. There is no immediatereplay to @code{step} until the next breakpoint is reached, and theprogram stops executing.@item	last signal     @code{?}This returns one of the following:@itemize @bullet@item @code{SAA}Where @code{AA} is the number of the last signal.Exceptions on the target are converted to the most similar Unix stylesignal number, like @code{SIGSEGV}. A sample response of this type wouldlook like @code{$S05#}.@item TAAnn:XXXXXXXX;nn:XXXXXXXX;nn:XXXXXXXX;@code{AA} is the signal number.@code{nn} is the register number.@code{XXXXXXXX} is the register value.@item WAAThe process exited, and @code{AA} is the exit status.  This is onlyapplicable for certains sorts of targets.@end itemizeThese are used in some GDB backends, but not all. @item write reg         @code{Pnn=XXXXXXXX}Write register @code{nn} with value @code{XXXXXXXX}.returns @code{ACK} or @code{NAK}@item	kill request	k@item	toggle debug	dtoggle debug flag (see 386 & 68k stubs)@item	reset		rreset -- see sparc stub.@item	reserved	@code{other}On other requests, the stub should ignore the request and send an emptyresponse @code{$#<checksum>}.  This way we can extend the protocol and GDBcan tell whether the stub it is	talking to uses the old or the new.@item	search		@code{tAA:PP,MM}Search backwards starting at address @code{AA} for a match with patternPP and mask @code{MM}. @code{PP} and @code{MM} are 4 bytes.