# Serial programming C library
[LPC2xxx related tools running on the host]

The LPC2xxx series chips have an on-chip bootloader that allows programming the chip through a serial line, eliminating the need for a JTAG interface hardware. More...

## Data Structures
struct | LPC_CHIP_CPU
| Structure holding info about the the CPU HW. More...
struct | LPC_CHIP_ROM
| Structure holding info about the FLASH. More...
struct | LPC_CHIP_RAM
| Structure holding info about the (main) RAM. More...
struct | LPC_CHIP
| Structure describing a chip. More...
struct | LPC_IO
| File I/O descriptor. More...
struct | LPC_IO_FUNC
| File type specific function table. More...
## Enumerations
enum | LPC_CONTROL_MODE { LPC_MODE_pDTR = 0, LPC_MODE_nDTR = 1, LPC_MODE_pRTS = 2, LPC_MODE_nRTS = 3 }
| Signal control modes. More...
enum | LPC_LOG_TYPE { LPC_LOG_TIMESTAMP = 0, LPC_LOG_ERROR, LPC_LOG_SERIAL, LPC_LOG_TARGET, LPC_LOG_FILEIO, LPC_LOG_NUMLOG }
| Log types. More...
enum | LPC_CONTROL { LPC_RES_ASSERT = 0, LPC_RES_NEGATE, LPC_ISP_ASSERT, LPC_ISP_NEGATE }
| Target control. More...
enum | LPC_ERROR { LPC_ERROR_CONFIG = -1, LPC_ERROR_SYSTEM = -2, LPC_ERROR_CHIP = -3, LPC_ERROR_COMMS = -4, LPC_ERROR_PARAM = -5, LPC_ERROR_PROTECT = -6, LPC_ERROR_SECTOR = -7, LPC_ERROR_BUSY = -8, LPC_ERROR_FAIL = -9, LPC_ERROR_COMMAND = -10, LPC_ERROR_LOCKED = -11, LPC_ERROR_FLASH = -12, LPC_ERROR_ADDRESS = -13, LPC_ERROR_UNKNOWN = -14, LPC_ERROR_FILE = -15, LPC_ERROR_FILETYPE = -16, LPC_ERROR_CBACK = -17 }
| Error codes. More...
## Functions
LPC_ERROR | LPC_LogOpen (LPC lpc, const char *file, int append)
| Open the logfile.
void | LPC_LogClose (LPC lpc)
| Closes the logfile.
void | LPC_LogEnable (LPC lpc, LPC_LOG_TYPE type)
| Enables the logging of certain events.
void | LPC_LogDisable (LPC lpc, LPC_LOG_TYPE type)
| Disables the logging of certain events.
char * | LPC_LogLastError (LPC lpc)
| Returns the last error.
void | LPC_LogCallback (LPC lpc, void(*func)(void *, const char *), void *user)
| Establishes a log callback.
LPC_ERROR | LPC_FileType (LPC lpc, const LPC_IO_FUNC *ftab)
| Register a new file type.
LPC_ERROR | LPC_FileOpen (LPC lpc, LPC_IO *io, const char *name, const char *type, int wr)
| Open a file for subsequent processing.
LPC_ERROR | LPC_FileRead (LPC_IO *io)
| Read a record from an already open file.
LPC_ERROR | LPC_FileWrite (LPC_IO *io)
| Write data to an already open file.
LPC_ERROR | LPC_FileClose (LPC_IO *io)
| Close a file.
LPC | LPC_Open (void)
| Opens the library.
void | LPC_Close (LPC lpc)
| Closes the library.
LPC_ERROR | LPC_SerialOpen (LPC lpc, const char *name, const char *lock)
| Open the serial port.
void | LPC_SerialClose (LPC lpc)
| Close the serial port.
LPC_ERROR | LPC_SerialBaud (LPC lpc, int baud)
| Sets the initial baud rate on the serial port.
LPC_ERROR | LPC_SerialSignal (LPC lpc, int rts, int val)
| Set a modem control signal to the given state.
LPC_ERROR | LPC_SerialWrite (LPC lpc, const void *ptr, int len)
| Writes data to the serial port.
LPC_ERROR | LPC_SerialRead (LPC lpc, void *ptr, int len, int tim)
| Reads data from the serial port with a timeout.
int | LPC_SerialPort (LPC lpc)
| Get the file descriptor of the serial port.
LPC_ERROR | LPC_TargetCrystal (LPC lpc, int freq)
| Set the crystal frequency of the target.
LPC_ERROR | LPC_TargetBaud (LPC lpc, int baud, int fast)
| Set the baud rate to talk to the target.
LPC_ERROR | LPC_TargetControlManual (LPC lpc, int(*func)(LPC_CONTROL, void *), void *param)
| Assign the target control signals to a user function.
LPC_ERROR | LPC_TargetControlModem (LPC lpc, LPC_CONTROL_MODE reset, LPC_CONTROL_MODE isp)
| Assign the target control signals to modem control signals.
LPC_ERROR | LPC_TargetReset (LPC lpc, int val)
| Control of the target's reset signal.
LPC_ERROR | LPC_TargetIsp (LPC lpc, int val)
| Control of the target's ISP signal.
void | LPC_TargetPower (LPC lpc, void(*func)(int, void *), void *user)
| Registers a power-up callback function.
LPC_ERROR | LPC_TargetConnect (LPC lpc)
| Attempt to connect to the target.
LPC_ERROR | LPC_TargetMemWrite (LPC lpc, int addr, const void *data, int dlen)
| Write data to the RAM on the target.
LPC_ERROR | LPC_TargetMemRead (LPC lpc, int addr, void *data, int dlen)
| Reading the target's RAM or FLASH.
LPC_ERROR | LPC_TargetExecute (LPC lpc, int addr, int thumb)
| Execute code on the target.
LPC_ERROR | LPC_TargetFlash (LPC lpc, int addr, const void *data, int dlen)
| Write data to the FLASH of the target.
LPC_ERROR | LPC_TargetErase (LPC lpc, int first, int last)
| Erase one or more sectors of the FLASH.
LPC_ERROR | LPC_TargetBlank (LPC lpc, int first, int last)
| Blank check a range of sectors of the target.
LPC_ERROR | LPC_TargetSector (LPC lpc, unsigned addr)
| Map an address to a sector number.
const LPC_CHIP * | LPC_TargetChip (LPC lpc)
| Obtain the current chip descriptor.
LPC_ERROR | LPC_TargetCompare (LPC lpc, int adr1, int adr2, int dlen)
| Compares two regions of the target.
void | LPC_TargetVectab (LPC lpc, void *vectab)
| Calculates the checksum of the vector table.

## Detailed Description

The LPC2xxx series chips have an on-chip bootloader that allows programming the chip through a serial line, eliminating the need for a JTAG interface hardware.

This library provides access to the LPC2xxxx ISP (In-System Programming) functionality. It can be used to read/write the FLASH of the target chip, read or write the RAM and execute code on the target. In addition, convenience functions are provided to load and store files in Motorola S-record or Intel-hex format.
The library has several function groups.

## Highest level functions

Before using it, you have to open the library using the LPC_Open() call. It will return a pointer to an opaque object, containing all the internal state of the library. You will need to supply this object to every call.
In this group you also find logging functions, so that you can trace what goes on between your computer and the target.

## Serial port low level functions

All functions in this group has an `LPC_Serial` prefix. This group contains the functionality that deals with the low level control of the serial port. Apart from opening the port, if you only want to program the target or read its content, you will not need to use these functions. They are provided, however, to facilitate you writing your own access functions to the target.

## Target functions

This group, which has the prefix of `LPC_Target` contains the functions that can be used to establish a link to the target, to access its FLASH and RAM. These functions deliver the functionality provided by the ISP of the target but hide the actual low level serial communication details.

## Logging functions

## Enumeration Type Documentation

enum LPC_CONTROL

Target control.

Enumerator:

  LPC_RES_ASSERT | Assert the reset signal.
  LPC_RES_NEGATE | Negate the reset signal.
  LPC_ISP_ASSERT | Assert the ISP signal.
  LPC_ISP_NEGATE | Negate the ISP signal.

enum LPC_CONTROL_MODE

Signal control modes.

Enumerator:

  LPC_MODE_pDTR | DTR with positive polarity.
  LPC_MODE_nDTR | DTR with negative polarity.
  LPC_MODE_pRTS | RTS with positive polarity.
  LPC_MODE_nRTS | RTS with negative polarity.

enum LPC_ERROR

Error codes.

Enumerator:

  LPC_ERROR_CONFIG | Invalid configuration or command order.
  LPC_ERROR_SYSTEM | A UNIX system call reported an error.
  LPC_ERROR_CHIP | Unknown chip type.
  LPC_ERROR_COMMS | Communication with the target failed.
  LPC_ERROR_PARAM | Invalid command parameter.
  LPC_ERROR_PROTECT | Target is read-protected.
  LPC_ERROR_SECTOR | Target reported a sector number error.
  LPC_ERROR_BUSY | Target reported a FLASH busy state.
  LPC_ERROR_FAIL | Target test (blank or compare) failed.
  LPC_ERROR_COMMAND | Target command or parameter invalid.
  LPC_ERROR_LOCKED | Target sector is locked.
  LPC_ERROR_FLASH | Target FLASH write verify failed.
  LPC_ERROR_ADDRESS | Target reported an address error.
  LPC_ERROR_UNKNOWN | Target response is not a known error code.
  LPC_ERROR_FILE | File format error.
  LPC_ERROR_FILETYPE | Duplicate file type identifier.
  LPC_ERROR_CBACK | Target control callback failure.

enum LPC_LOG_TYPE

Log types.

Enumerator:

  LPC_LOG_TIMESTAMP | Have a delta time for each entry.
  LPC_LOG_ERROR | Log errors (always on).
  LPC_LOG_SERIAL | Log serial events.
  LPC_LOG_TARGET | Log target activity.
  LPC_LOG_FILEIO | Log access to files.
  LPC_LOG_NUMLOG | Number of types of logs.

## Function Documentation

void LPC_Close | ( | LPC | lpc | ) |

Closes the library.

The function closes down the library. All open files are closed, all allocated resources, including the `lpc` object itself is freed.

Parameters:

  | lpc | The state descriptor

LPC_ERROR LPC_FileClose | ( | LPC_IO * | io | ) |

Close a file.

Parameters:

  | io | Pointer to an LPC_IO descriptor which must have been prepared by a call to LPC_FileOpen().

Returns:
  0 on success and a negative error code in case of an error. The file will be closed and all associated state will be released in any case

LPC_ERROR LPC_FileOpen | ( | LPC | lpc,
|  | LPC_IO * | io,
|  | const char * | name,
|  | const char * | type,
|  | int | wr |
| ) |  |  |

Open a file for subsequent processing.

Parameters:

  | lpc | The library state pointer
  | io | Pointer to an LPC_IO descriptor. The interpretation of the fields of the descriptor is up to the actual file format dependent implementation. The `srec` and `ihex` implementations do not use any fields in the structure.
  | name | The name of the file to be opened or created
  | type | The name of the file type, like "srec" or "ihex"
  | wr | A flag indicating write. If this argument is non-zero, then a file with the given name will be created (or if the file exists, its size will be truncated to 0) and LPC_FileWrite() calls can write into the file. If the argument is 0, then an existing file is opened and can be read by calls to LPC_FileRead().

Returns:
  0 on success, a negative error code on failure.

LPC_ERROR LPC_FileRead | ( | LPC_IO * | io | ) |

Read a record from an already open file.

The file must have been opened for reading, using the LPC_FileOpen() function. This call will read one record and place it in a buffer.
At entry:

- io->data
  Contains a pointer to a buffer. This buffer will contain the data read from the file. If this pointer is NULL, then data will be consumed from the file and then discarded.
- io->rlen
  The size of the buffer, in bytes.
- io->addr
  The value of this field is not used by the `srec` and `ihex` readers, it might be used for any purpose in a user-implemented reader.
- io->line
  The value of this field is not used by the `srec` and `ihex` readers, it might be used for any purpose in a user-implemented reader.

At exit:

- io->data
  The field is unchanged. If it is not NULL, then the data read from the file is placed into the memory area pointed by it.
- io->rlen
  The number of bytes placed into the data buffer. It might be 0.
- io->addr
  The address associated with the record read from the file. If data was placed into the buffer, then this is the target address corresponding to the first data byte.
- io->line
  Implementation dependent. For the `srec` and `ihex` readers it will contain the line number that supplied the record.

Parameters:

  | io | Pointer to an LPC_IO descriptor which must have been prepared by a call to LPC_FileOpen() specifying read mode.

Return values:

  | >0 | A record has been read. The actual numerical value is implementation dependent. The `srec` and `ihex` readers always return 1 on success.
  | 0 | The last record in the file was processed. Any further calls will immediately return 0 with data length of 0.
  | <0 | There was some error, the returned value is one of the LPC_ERROR codes.

LPC_ERROR LPC_FileType | ( | LPC | lpc,
|  | const LPC_IO_FUNC * | ftab |
| ) |  |  |

Register a new file type.

The function receives a file I/O function table and adds it to the list of know file types. After this call, the new type identified by the 'name' field of the LPC_IO_FUNC structure can be used just like the built-in types.

Parameters:

  | lpc | The library state pointer
  | ftab | File handling function table

Returns:
  0 on success, a negative error code on failure.

LPC_ERROR LPC_FileWrite | ( | LPC_IO * | io | ) |

Write data to an already open file.

The file must have been opened for writing, using the LPC_FileOpen() function. This call will write some amount of data into the file.
At entry:

- io->data
  A pointer to a buffer that contains the data to be written into the file. If it is NULL, then the behaviour depends on the actual file format implementation. The `srec` and `ihex` functions ignore calls with a NULL pointer.
- io->rlen
  The size of the buffer, in bytes. That many bytes will be written to the file, at consecutive addresses. io->addr
  The target address that corresponds to the first byte in the buffer.
- io->line
  The value of this field can be interpreted by any way by the implementation. The `srec` and `ihex` routines interpret it as the maximum number of data bytes written per line; if it is less that 16, then 16 will be used.

At exit:

- io->data
  The field is unchanged.
- io->rlen
  Implementation dependent, the `srec` and `ihex` routines do not return anything in this field.
- io->addr
  Implementation dependent, the `srec` and `ihex` routines do not return anything in this field.
- io->line
  Implementation dependent. For the `srec` and `ihex` readers it will contain the number of lines written to the file so far.

Parameters:

  | io | Pointer to an LPC_IO descriptor which must have been prepared by a call to LPC_FileOpen() specifying write mode.

Return values:

  | >=0 | The data was written out. The actual numerical value if implementation dependent. The `srec` and `ihex` readers always return 1 on success.
  | <0 | There was some error, the returned value is one of the LPC_ERROR codes.

void LPC_LogCallback | ( | LPC | lpc,
|  | void(*)(void *, const char *) | func,
|  | void * | user |
| ) |  |  |

Establishes a log callback.

Using this function the caller can set up a callback function, which will be called whenever the library logs something. The callback function will receive a user-specified argument and a pointer to the log string. The callback MUST NOT modify the log string, nor should it cache a pointer to it as it will go out of existence as soon as the callback returns. if the user wants to keep the log entry, then the callback must create a copy of the string.

The log callback is called regardless of whether logging to a file is enabled or not, but the log types established by LPC_LogEnable() and LPC_LogDisable() are respected.

Passing a NULL pointer as the callback function is legal and simply turns the service off.

The line passed to the callback is a 0-terminated string. There is no newline at the end of the string.

Parameters:

  | lpc | The library state
  | func | The callback function. The function prototype should be `void callback( void *user, const char *logline );`
  | user | The first parameter of the callback function.

void LPC_LogClose | ( | LPC | lpc | ) |

Closes the logfile.

Parameters:

  | lpc | The library state

void LPC_LogDisable | ( | LPC | lpc,
|  | LPC_LOG_TYPE | type |
| ) |  |  |

Disables the logging of certain events.

The function enables the logging of event classes, as defined by the LPC_LOG_TYPE enumerator. A call to this function disables the logging of the class defined by the argument. Logging of errors can not be disabled.

Parameters:

  | lpc | The library state
  | type | The log class to enable.

void LPC_LogEnable | ( | LPC | lpc,
|  | LPC_LOG_TYPE | type |
| ) |  |  |

Enables the logging of certain events.

The function enables the logging of event classes, as defined by the LPC_LOG_TYPE enumerator. A call to this function enables the logging of the class defined by the argument.

Parameters:

  | lpc | The library state
  | type | The log class to enable.

char* LPC_LogLastError | ( | LPC | lpc | ) |

Returns the last error.

If there was an error, a textual error message is logged and the API function returns to the caller with an error code. This function returns a malloc() -ed string that contains the error message (if there was no error since the library was opened or since the last call to this function, NULL is returned). It is the responsibility of the caller to release the string after use.

Parameters:

  | lpc | The library state

Returns:
  A malloc()-ed string containing the last error message or NULL, if there was no error since the last call.

LPC_ERROR LPC_LogOpen | ( | LPC | lpc,
|  | const char * | file,
|  | int | append |
| ) |  |  |

Open the logfile.

The function opens a log file. Events will be written into the file.

Parameters:

  | lpc | The library state
  | file | The name of the ligfile to open. The caller must have write permission on the file. If the file specified is "-", i.e. a single dash, then the all log info will be sent to the stdout.
  | append | If non-zero, the file will be opened for append, otherwise it will be truncated to 0 length before logging commences.

Returns:
  0 on success, a negative error code on failure.

LPC LPC_Open | ( | void |  | ) |

Opens the library.

The function prepares the library for use. It creates an instance of the opaque state descriptor and returns a pointer to it.

It is possible to call this function multiple times and use the library on multiple serial ports and targets simultaneously.

Returns:
  A new, initialised LPC object on success or NULL if the allocation of the state descriptor failed.

LPC_ERROR LPC_SerialBaud | ( | LPC | lpc,
|  | int | baud |
| ) |  |  |

Sets the initial baud rate on the serial port.

Sets the baud rate of the serial port. After this call the serial port will use the baud rate specified by the argument. Note that if you are already connected to the target, you have to change the target's baud rate before you call this function. The function returns the new baud rate. If called with the argument of 0, then no baud rate change is done, just the current baud rate is returned.

Parameters:

  | lpc | Pointer to the library state descriptor
  | baud | The desired baud rate, one of 1200, 2400, 4800, 9600, 19200, 38400, 57600 or 115200 or 0, if no baud rate change is required.

Returns:
  The baud rate after the call, or a negative number in case of error.

void LPC_SerialClose | ( | LPC | lpc | ) |

Close the serial port.

If the serial port is open, then the function will close it. If the target was connected, it will now be disconnected. The baud rate settings. This function can not fail.

Parameters:

  | lpc | Pointer to the library state descriptor

LPC_ERROR LPC_SerialOpen | ( | LPC | lpc,
|  | const char * | name,
|  | const char * | lock |
| ) |  |  |

Open the serial port.

The function tries to open the serial port. It returns 0 on success and a negative number on failure. In the latter case the error message can be retrieved by a call to the _lpc_ErrorMsg() function.

Parameters:

  | lpc | Pointer to the library state descriptor
  | name | The name of the serial device to open, such as `/dev/ttyS0` or `/dev/ttyUSB2`. The caller must have read-write permissions on the device.
  | lock | The name of the lockfile. If you pass NULL here, then no locking will be used. If you pass a pointer that points to an empty string (i.e. to a 0 byte), then flock() will be called to request an exlusive advisory lock on the file. If the argument points to a string, then it is assumed that it is the full pathname of the lockfile. The caller must have permissions to create a file in in the lockfile directory.

int LPC_SerialPort | ( | LPC | lpc | ) |

Get the file descriptor of the serial port.

This function can be useful when you want to control the serial communication with the target completely.

The function returns the (non-negative) file descriptor belonging to the already open serial port of -1 if the port is not open. Note that if you modify the serial port state without the knowledge of the library, library functions might not work later.

Parameters:

  | lpc | Pointer to the library state descriptor

Returns:
  The serial port's file descriptor or -1 if it's not open.

LPC_ERROR LPC_SerialRead | ( | LPC | lpc,
|  | void * | ptr,
|  | int | len,
|  | int | tim |
| ) |  |  |

Reads data from the serial port with a timeout.

Waits until the requested number of characters is received, a newline was read or the timeout value (given in millisec) elapses. Returns -1 on error or the number of characters received otherwise.

Parameters:

  | lpc | Pointer to the library state descriptor
  | ptr | Pointer to the buffer where the result is stored. The buffer must be one byte longer than the requested read length, because a 0 byte will be placed after the last received character (makes life easier if you deal with strings, doesn't hurt otherwise).
  | len | The max. number of bytes to receive
  | tim | Read timeot, in millisecs. This time is the maximum time the function waits from its start, that is, the wait times between characters are accumulated. If the timeout is 0, the the call returns immediately.

Returns:
  The number of characters received on success, or a negative error code on failure.

LPC_ERROR LPC_SerialSignal | ( | LPC | lpc,
|  | int | rts,
|  | int | val |
| ) |  |  |

Set a modem control signal to the given state.

Sets the given signal to active or inactive state, depending on the `val` argument.

Parameters:

  | lpc | Pointer to the library state descriptor
  | rts | Selest which signal to change. If it is non-zero, the the RTS signal is affected, if it is 0, then the DTR is affected.
  | val | A logical value. If it is non-zero, then the given modem control signal vill be activated, that is, it will be LOW on the TTL level and positive voltage on the RS-232 line. If it is 0, then the signal will be deactivated, that is, HIGH TTL level and negative voltage on the RS-232 line.

Returns:
  0 on success, a negative error code on failure.

LPC_ERROR LPC_SerialWrite | ( | LPC | lpc,
|  | const void * | ptr,
|  | int | len |
| ) |  |  |

Writes data to the serial port.

The function writes data to the serial port. It is pretty much equivalent to a raw write() to the port, with some error checking. The function always writes the entire length of the data.

Parameters:

  | lpc | Pointer to the library state descriptor
  | ptr | Pointer to the data to write
  | len | The number of bytes to write

Returns:
  The length on success, a negative error code on failure.

LPC_ERROR LPC_TargetBaud | ( | LPC | lpc,
|  | int | baud,
|  | int | fast |
| ) |  |  |

Set the baud rate to talk to the target.

This function sets the initial baud rate with which the target will be contacted. It doesn't do anything with the target, just prepares internal data for a subsequent call to LPC_TargetConnect(). If the `fast` parameter is larger than `baud`, then after contacting the target the LPC_TargetConnect() function negotiates the highest baudrate achievable with the target's clock frequency but still not larger than the `fast` argument and switches to that rate. If the parameter is less than or equal to `baud`, then the initial baud rate is kept.
Due to the limitations of the ISP, only speeds of 9600, 19200, 38400, 57600 and 115200 baud are supported.

Attention:
  On some systems changing the baudrate also resets the modem control signals, resetting the target. On such systems you must not enable fast mode. On x86 Linux it is safe to use the fast mode with the standard PC serial ports as well as with USB-serial adapters.

Parameters:

  | lpc | Pointer to the library state descriptor
  | baud | The initial baud rate. If this value is 0, then the settings are not changed, just the current baudrate setting is returned. In that case, if the `fast` argument is 0, then the returned value is the initial baud rate and if non-zero, the fast baud rate is returned. Note that after connecting to the target the fast baud rate value is updated to the actual negotiated value.
  | fast | The highest baud rate that is allowed to be used. If this number is less than or equal to the `baud` argument, then no speed-up is attempted. Otherwise, after the initial connection a higher baud rate might be selected. This argument puts an upper limit on that baud rate, but it is not guaranteed that a higher baud rate will be selected at all, as it depends on the clock frequency of the target and other factors.

Returns:
  The initial baud rate after the call or -1 if the specified baud rate is not valid.

LPC_ERROR LPC_TargetBlank | ( | LPC | lpc,
|  | int | first,
|  | int | last |
| ) |  |  |

Blank check a range of sectors of the target.

The function checks if the given sector of the target is blank or not.

Parameters:

  | lpc | Pointer to the library state descriptor
  | first | The first sector to test
  | last | The last sector to test, greater than or equal to first

Returns:
  1 if the sector is blank, 0 if it is not blank and a negative error code on failure.

const LPC_CHIP* LPC_TargetChip | ( | LPC | lpc | ) |

Obtain the current chip descriptor.

The function returns a pointer to the descriptor of the current target chip.

Parameters:

  | lpc | Pointer to the library state descriptor

Returns:
  The pointer to the chip descriptor or NULL if the target is not known.

LPC_ERROR LPC_TargetConnect | ( | LPC | lpc | ) |

Attempt to connect to the target.

This function tries to establish connection to the target. The serial port must be open. The initial baud rate must have been set by the LPC_TargetBaud() call. The reset and ISP signals must have been bound by the LPC_SerialBind() call.
This function resets the target, puts it into ISP mode, establishes the serial link and reads the chip ID. If the chip supports a higher baud rate and the use of such baud rate was allowed, then both the target and the serial port are reconfigured to use the higher rate.
If the chip is the kind that has no internal oscillator, for example the LPC210x series, then it is mandatory that the crystal frequency is set by calling LPC_TargetCrystal() before calling this function. If you don't do that, you will get an `LPC_ERROR_CONFIG` code.

Parameters:

  | lpc | Pointer to the library state descriptor

Returns:
  The negotiated baud rate on success or a negative error code on failure.

LPC_ERROR LPC_TargetControlManual | ( | LPC | lpc,
|  | int(*)(LPC_CONTROL, void *) | func,
|  | void * | param |
| ) |  |  |

Assign the target control signals to a user function.

Although most often the target's reset and ISP signals are controlled using the serial port's RTS and DTR signals, in some cases your target might not have those signals connected. In that case the controlling of the reset and ISP can be delegated to your program, which can do anything it wishes (e.g. telling the user to manually assert/negate the signals). This function takes a function and a parameter. Whenever the reset or ISP signal of your target needs to be changed, the function you passed as the first argument will be called. That function, in turn, will get two arguments. The first argument is an LPC_CONTROL enumerator type, which is one of LPC_RES_ASSERT, LPC_RES_NEGATE, LPC_ISP_ASSERT or LPC_ISP_NEGATE telling you what to do. The second argument, a void pointer is the pointer that you specified as the second argument of this function.

Parameters:

  | lpc | Pointer to the library state descriptor
  | func | A function pointer for manual signal assertion. If this pointer is NULL, then all signal associations will be deleted. Otherwise, the pointer must be to a function taking an int and a void * argument. The function will be called every time a target control signal has to be changed. It should return 0 in case of failure and !0 in case of success.
  | param | A void pointer, which will be passed to the function specified by the `func` argument.

Returns:
  0 on success, negative error code on failure

LPC_ERROR LPC_TargetControlModem | ( | LPC | lpc,
|  | LPC_CONTROL_MODE | reset,
|  | LPC_CONTROL_MODE | isp |
| ) |  |  |

Assign the target control signals to modem control signals.

The target chip's reset and ISP signals are assumed to be driven by the modem control signals of RTS and DTR. This function binds the target control signals to the modem control signals and sets up the active polarity for them.
This function does nothing on the actual lines, it simply sets up an association. Therefore, this function can be called even when the serial port is not open.
Although most often the above mentioned modem control signals are used to control the target, if your target board does not use those signals, then it is possible to set up a custom signal control. In that case you provide a callback function that will be called whenever a control signal should be changed. The function returns void and has two integer arguments. The first argument is set to 0 if the signal to control is the reset and 1 if the signal to set is the chip's ISP pin. The second argument is 1 if the signal selected by the first argument should be asserted and 0 if it should be negated.

Parameters:

  | lpc | Pointer to the library state descriptor
  | reset | The control signal and polarity for the target's reset signal. It is one of the values defined by the enum LPC_CONTOL_MODE.
  | isp | The control signal and polarity for the target's ISP signal. It is one of the values defined by the enum LPC_CONTOL_MODE.

Returns:
  0 on success, negative error code on failure

LPC_ERROR LPC_TargetCrystal | ( | LPC | lpc,
|  | int | freq |
| ) |  |  |

Set the crystal frequency of the target.

The LPC chips must know their clock frequency in order to time FLASH accesses. This function sets the frequency that the target chips runs during programming. Some chips, notably the LPC23xx series, run from an internally generated clock for which the frequency is known. Others, for example the LPC210x chips run from the frequency of their external crystal. The latter class of chips must be told about their clock. This call can be used for that. It must be called before LPC_TargetConnect() is called. The function does nothing to the target, it just makes a note of the frequency, which will subsequently be used by the LPC_TargetConnect() function.

Parameters:

  | lpc | Pointer to the library state descriptor
  | freq | The crystal frequency, in Hz. If set to 0, then no change is done, just the current frequency is returned.

Returns:
  The current frequency. It might be different from the setting, if the target chip runs from its internal oscillator.

LPC_ERROR LPC_TargetErase | ( | LPC | lpc,
|  | int | first,
|  | int | last |
| ) |  |  |

Erase one or more sectors of the FLASH.

Erases all sectors between `first` and `last`, inclusive. After the erase it checks if the sectors are indeed blank.

Parameters:

  | lpc | Pointer to the library state descriptor
  | first | The first sector to erase
  | last | The last sector to erase. If you want to erase only one sector, then set this argument to the same value as `first`. The `last` argument must larger than or equal to the `first` argument.

Returns:
  0 on success, a negative error code on failure. In case of a sector being non-blank after erase, LPC_ERROR_FAIL is returned.

LPC_ERROR LPC_TargetExecute | ( | LPC | lpc,
|  | int | addr,
|  | int | thumb |
| ) |  |  |

Execute code on the target.

The function transfer control from the ISP code to any code on the target. The function does not wait for the code to complete, it returns immediately.

Parameters:

  | lpc | Pointer to the library state descriptor
  | addr | The address where code execution should start. For ARM code it must be on 4-byte boundary, for THUMB code it must be on a 2-byte boundary.
  | thumb | If this argument is non-zero, then code execution will start in THUMB modem, if it is 0, then the code will be executed in ARM mode.

Returns:
  0 on success or a negative error code on failure.

LPC_ERROR LPC_TargetFlash | ( | LPC | lpc,
|  | int | addr,
|  | const void * | data,
|  | int | dlen |
| ) |  |  |

Write data to the FLASH of the target.

This call writes data to the target's FLASH. It does not erase the FLASH, you must have erased the relevant sector(s) beforehand. It does, however, verify that the FLASH write was successful

Parameters:

  | lpc | Pointer to the library state descriptor
  | addr | The start address in the FLASH. It must be on a 256 byte boundary.
  | data | Pointer to the data to be written into the FLASH
  | dlen | The length of the data to be written. It must be a multiple or 256 bytes.

Returns:
  0 on success, a negative error code on failure.

LPC_ERROR LPC_TargetIsp | ( | LPC | lpc,
|  | int | val |
| ) |  |  |

Control of the target's ISP signal.

This call asserts or negates the ISP signal of the target. The signal must have already be bound by the LPC_TargetControl() call.

Parameters:

  | lpc | Pointer to the library state descriptor
  | val | If non-zero, the ISP signal will be asserted. If zero, ISP will be negated.

Returns:
  0 on success, -1 if the modes specified are illegal.

LPC_ERROR LPC_TargetMemRead | ( | LPC | lpc,
|  | int | addr,
|  | void * | data,
|  | int | dlen |
| ) |  |  |

Reading the target's RAM or FLASH.

The function can be used to read the FLASH or the main RAM of the target. You can not read from peripheral registers or RAM blocks associated with peripheral units.

Parameters:

  | lpc | Pointer to the library state descriptor
  | addr | The address in the target's RAM or FLASH. It must be word aligned, that is, a multiple of 4.
  | data | Pointer to a buffer in the host's memory, where the data read from the target will be stored. The data will be stored as bytes, not words.
  | dlen | The number of bytes to transfer. It must be a multiple of 4.

Returns:
  0 on success or a negative error code on failure.

LPC_ERROR LPC_TargetMemWrite | ( | LPC | lpc,
|  | int | addr,
|  | const void * | data,
|  | int | dlen |
| ) |  |  |

Write data to the RAM on the target.

The function writes data to the target's main RAM. You can not write data to the peripheral registers or RAM belonging to peripherals.

Parameters:

  | lpc | Pointer to the library state descriptor
  | addr | The address in the target's RAM. It must be word aligned, that is, a multiple of 4.
  | data | Pointer to data in the host's memory. The data pointed will be copied into the target's RAM as bytes, not as words.
  | dlen | The number of bytes to transfer. It must be a multiple of 4.

Returns:
  0 on success or a negative error code on failure.

void LPC_TargetPower | ( | LPC | lpc,
|  | void(*)(int, void *) | func,
|  | void * | user |
| ) |  |  |

Registers a power-up callback function.

In some cases the target's ISP goes into a funny state where it ignores the ISP signal after a reset. In that case the only way to enter the ISP mode is powering up the target while the reset is held low. This function allows a user callback to be set up which will be called when the target power should be removed or applied. The callback will receive two arguments. The first one isan integer, which is 0 for removing the power and 1 for powering up. The second argument of the callback is a void pointer, which will be the same as what this function receives in its third parameter.

Calling this function with a NULL finction will remove the callback.

Parameters:

  | lpc | Pointer to the library state descriptor
  | func | The callback function
  | user | The first argument to the function

LPC_ERROR LPC_TargetReset | ( | LPC | lpc,
|  | int | val |
| ) |  |  |

Control of the target's reset signal.

This call asserts or negates the reset signal of the target. The signal must have already be bound by the LPC_TargetControl() call.

Parameters:

  | lpc | Pointer to the library state descriptor
  | val | If non-zero, the reset signal will be asserted. If zero, reset will be negated.

Returns:
  0 on success, -1 if the modes specified are illegal.

LPC_ERROR LPC_TargetSector | ( | LPC | lpc,
|  | unsigned | addr |
| ) |  |  |

Map an address to a sector number.

The function receives an address and returns the FLASH sector number that contains the address. If the address is not within the FLASH, it returns `LPC_ERROR_PARAM`, or, if the chip type is not yet known, `LPC_ERROR_CHIP`.

Parameters:

  | lpc | Pointer to the library state descriptor
  | addr | The address in the FLASH

Returns:
  The sector number, which is >= 0, or a negative error code.

void LPC_TargetVectab | ( | LPC | lpc,
|  | void * | vectab |
| ) |  |  |

Calculates the checksum of the vector table.

The LPC2xxx chips use an otherwise empty slot in the ARM vector table to store a checksum of the vectors in the table. If the checksum does not match, the chip assumes that its FLASH does not contain valid code and does drop into the on-chip bootloader. If the checksum is correct, then it executes the user code in the FLASH.
This function receives a pointer to a 32-byte memory block (the size of the ARM vector table) and calculates and fills in the checksum.

Parameters:

  | lpc | Pointer to the library state descriptor
  | vectab | A pointer to a 32-byte memory block which is assumed to contain the ARM vector table. The checksum of that block is calculated and the result is written back into the same memory block. The memory block should be in the target's format (i.e. little-endian).