/*********************************************************************
*
* SEGGER_RTT_SetTerminal
*
* Function description
* Sets the terminal to be used for output on channel 0.
*
* Parameters
* TerminalId Index of the terminal.
*
* Return value
* >= 0 O.K.
* < 0 Error (e.g. if RTT is configured for non-blocking mode and there was no space in the buffer to set the new terminal Id)
*/
int SEGGER_RTT_SetTerminal (char TerminalId) {
char ac[2];
SEGGER_RTT_BUFFER_UP* pRing;
unsigned Avail;
int r;
//
INIT();
//
r = 0;
ac[0] = 0xFFU;
if ((unsigned char)TerminalId < (unsigned char)sizeof(_aTerminalId)) { // We only support a certain number of channels
ac[1] = _aTerminalId[(unsigned char)TerminalId];
pRing = &_SEGGER_RTT.aUp[0]; // Buffer 0 is always reserved for terminal I/O, so we can use index 0 here, fixed
SEGGER_RTT_LOCK(); // Lock to make sure that no other task is writing into buffer, while we are and number of free bytes in buffer does not change downwards after checking and before writing
if ((pRing->Flags & SEGGER_RTT_MODE_MASK) == SEGGER_RTT_MODE_BLOCK_IF_FIFO_FULL) {
_ActiveTerminal = TerminalId;
_WriteBlocking(pRing, ac, 2u);
} else { // Skipping mode or trim mode? => We cannot trim this command so handling is the same for both modes
Avail = _GetAvailWriteSpace(pRing);
if (Avail >= 2) {
_ActiveTerminal = TerminalId; // Only change active terminal in case of success
_WriteNoCheck(pRing, ac, 2u);
} else {
r = -1;
}
}
SEGGER_RTT_UNLOCK();
} else {
r = -1;
}
return r;
}
/*********************************************************************
*
* SEGGER_RTT_AllocDownBuffer
*
* Function description
* Run-time configuration of the next down-buffer (H->T).
* The next buffer, which is not used yet is configured.
* This includes: Buffer address, size, name, flags, ...
*
* Parameters
* sName Pointer to a constant name string.
* pBuffer Pointer to a buffer to be used.
* BufferSize Size of the buffer.
* Flags Operating modes. Define behavior if buffer is full (not enough space for entire message).
*
* Return value
* >= 0 - O.K. Buffer Index
* < 0 - Error
*/
int SEGGER_RTT_AllocDownBuffer(const char* sName, void* pBuffer, unsigned BufferSize, unsigned Flags) {
int BufferIndex;
INIT();
SEGGER_RTT_LOCK();
BufferIndex = 0;
do {
if (_SEGGER_RTT.aDown[BufferIndex].pBuffer == NULL) {
break;
}
BufferIndex++;
} while (BufferIndex < _SEGGER_RTT.MaxNumDownBuffers);
if (BufferIndex < _SEGGER_RTT.MaxNumDownBuffers) {
_SEGGER_RTT.aDown[BufferIndex].sName = sName;
_SEGGER_RTT.aDown[BufferIndex].pBuffer = (char*)pBuffer;
_SEGGER_RTT.aDown[BufferIndex].SizeOfBuffer = BufferSize;
_SEGGER_RTT.aDown[BufferIndex].RdOff = 0u;
_SEGGER_RTT.aDown[BufferIndex].WrOff = 0u;
_SEGGER_RTT.aDown[BufferIndex].Flags = Flags;
} else {
BufferIndex = -1;
}
SEGGER_RTT_UNLOCK();
return BufferIndex;
}
/*********************************************************************
*
* SEGGER_RTT_SetNameDownBuffer
*
* Function description
* Run-time configuration of a specific Down-buffer name (T->H).
* Buffer to be configured is specified by index.
*
* Parameters
* BufferIndex Index of the buffer to renamed.
* sName Pointer to a constant name string.
*
* Return value
* >= 0 O.K.
* < 0 Error
*/
int SEGGER_RTT_SetNameDownBuffer(unsigned BufferIndex, const char* sName) {
int r;
INIT();
if (BufferIndex < (unsigned)_SEGGER_RTT.MaxNumDownBuffers) {
SEGGER_RTT_LOCK();
_SEGGER_RTT.aDown[BufferIndex].sName = sName;
SEGGER_RTT_UNLOCK();
r = 0;
} else {
r = -1;
}
return r;
}
/*********************************************************************
*
* SEGGER_RTT_SetFlagsDownBuffer
*
* Function description
* Run-time configuration of specific Down-buffer flags (T->H).
* Buffer to be configured is specified by index.
*
* Parameters
* BufferIndex Index of the buffer to renamed.
* Flags Flags to set for the buffer.
*
* Return value
* >= 0 O.K.
* < 0 Error
*/
int SEGGER_RTT_SetFlagsDownBuffer(unsigned BufferIndex, unsigned Flags) {
int r;
INIT();
if (BufferIndex < (unsigned)_SEGGER_RTT.MaxNumDownBuffers) {
SEGGER_RTT_LOCK();
_SEGGER_RTT.aDown[BufferIndex].Flags = Flags;
SEGGER_RTT_UNLOCK();
r = 0;
} else {
r = -1;
}
return r;
}
/*********************************************************************
*
* SEGGER_RTT_Read
*
* Function description
* Reads characters from SEGGER real-time-terminal control block
* which have been previously stored by the host.
*
* Parameters
* BufferIndex Index of Down-buffer to be used (e.g. 0 for "Terminal").
* pBuffer Pointer to buffer provided by target application, to copy characters from RTT-down-buffer to.
* BufferSize Size of the target application buffer.
*
* Return value
* Number of bytes that have been read.
*/
unsigned SEGGER_RTT_Read(unsigned BufferIndex, void* pBuffer, unsigned BufferSize) {
unsigned NumBytesRead;
//
SEGGER_RTT_LOCK();
//
// Call the non-locking read function
//
NumBytesRead = SEGGER_RTT_ReadNoLock(BufferIndex, pBuffer, BufferSize);
//
// Finish up.
//
SEGGER_RTT_UNLOCK();
//
return NumBytesRead;
}
/*********************************************************************
*
* SEGGER_RTT_Write
*
* Function description
* Stores a specified number of characters in SEGGER RTT
* control block which is then read by the host.
*
* Parameters
* BufferIndex Index of "Up"-buffer to be used (e.g. 0 for "Terminal").
* pBuffer Pointer to character array. Does not need to point to a \0 terminated string.
* NumBytes Number of bytes to be stored in the SEGGER RTT control block.
*
* Return value
* Number of bytes which have been stored in the "Up"-buffer.
*
* Notes
* (1) If there is not enough space in the "Up"-buffer, remaining characters of pBuffer are dropped.
*/
unsigned SEGGER_RTT_Write(unsigned BufferIndex, const void* pBuffer, unsigned NumBytes) {
unsigned Status;
//
INIT();
SEGGER_RTT_LOCK();
//
// Call the non-locking write function
//
Status = SEGGER_RTT_WriteNoLock(BufferIndex, pBuffer, NumBytes);
//
// Finish up.
//
SEGGER_RTT_UNLOCK();
//
return Status;
}
/*********************************************************************
*
* SEGGER_RTT_Read
*
* Function description
* Reads characters from SEGGER real-time-terminal control block
* which have been previously stored by the host.
*
* Parameters
* BufferIndex Index of Down-buffer to be used. (e.g. 0 for "Terminal")
* pBuffer Pointer to buffer provided by target application, to copy characters from RTT-down-buffer to.
* BufferSize Size of the target application buffer
*
* Return values
* Number of bytes that have been read
*/
int32_t SEGGER_RTT_Read(unsigned BufferIndex, char* pBuffer, unsigned BufferSize) {
int32_t NumBytesRem;
unsigned NumBytesRead;
int32_t RdOff;
int32_t WrOff;
SEGGER_RTT_LOCK();
_Init();
RdOff = _SEGGER_RTT.aDown[BufferIndex].RdOff;
WrOff = _SEGGER_RTT.aDown[BufferIndex].WrOff;
NumBytesRead = 0;
//
// Read from current read position to wrap-around of buffer, first
//
if (RdOff > WrOff) {
NumBytesRem = _SEGGER_RTT.aDown[BufferIndex].SizeOfBuffer - RdOff;
NumBytesRem = MIN(NumBytesRem, (int32_t)BufferSize);
MEMCPY(pBuffer, _SEGGER_RTT.aDown[BufferIndex].pBuffer + RdOff, NumBytesRem);
NumBytesRead += NumBytesRem;
pBuffer += NumBytesRem;
BufferSize -= NumBytesRem;
RdOff += NumBytesRem;
//
// Handle wrap-around of buffer
//
if (RdOff == _SEGGER_RTT.aDown[BufferIndex].SizeOfBuffer) {
RdOff = 0;
}
}
//
// Read remaining items of buffer
//
NumBytesRem = WrOff - RdOff;
NumBytesRem = MIN(NumBytesRem, (int32_t)BufferSize);
if (NumBytesRem > 0) {
MEMCPY(pBuffer, _SEGGER_RTT.aDown[BufferIndex].pBuffer + RdOff, NumBytesRem);
NumBytesRead += NumBytesRem;
pBuffer += NumBytesRem;
BufferSize -= NumBytesRem;
RdOff += NumBytesRem;
}
if (NumBytesRead) {
_SEGGER_RTT.aDown[BufferIndex].RdOff = RdOff;
}
SEGGER_RTT_UNLOCK();
return NumBytesRead;
}
/*********************************************************************
*
* SEGGER_RTT_ConfigDownBuffer
*
* Function description
* Run-time configuration of a specific down-buffer (H->T).
* Buffer to be configured is specified by index.
* This includes: Buffer address, size, name, flags, ...
*
* Return value
* >= 0 O.K.
* < 0 Error
*/
int32_t SEGGER_RTT_ConfigDownBuffer(unsigned BufferIndex, const char* sName, char* pBuffer, int32_t BufferSize, int32_t Flags) {
_Init();
if (BufferIndex < (unsigned)_SEGGER_RTT.MaxNumDownBuffers) {
SEGGER_RTT_LOCK();
if (BufferIndex > 0) {
_SEGGER_RTT.aDown[BufferIndex].sName = sName;
_SEGGER_RTT.aDown[BufferIndex].pBuffer = pBuffer;
_SEGGER_RTT.aDown[BufferIndex].SizeOfBuffer = BufferSize;
_SEGGER_RTT.aDown[BufferIndex].RdOff = 0;
_SEGGER_RTT.aDown[BufferIndex].WrOff = 0;
}
_SEGGER_RTT.aDown[BufferIndex].Flags = Flags;
SEGGER_RTT_UNLOCK();
return 0;
}
return -1;
}
/*********************************************************************
*
* SEGGER_RTT_ConfigDownBuffer
*
* Function description
* Run-time configuration of a specific down-buffer (H->T).
* Buffer to be configured is specified by index.
* This includes: Buffer address, size, name, flags, ...
*
* Parameters
* BufferIndex Index of the buffer to configure.
* sName Pointer to a constant name string.
* pBuffer Pointer to a buffer to be used.
* BufferSize Size of the buffer.
* Flags Operating modes. Define behavior if buffer is full (not enough space for entire message).
*
* Return value
* >= 0 O.K.
* < 0 Error
*/
int SEGGER_RTT_ConfigDownBuffer(unsigned BufferIndex, const char* sName, void* pBuffer, unsigned BufferSize, unsigned Flags) {
int r;
INIT();
if (BufferIndex < (unsigned)_SEGGER_RTT.MaxNumDownBuffers) {
SEGGER_RTT_LOCK();
if (BufferIndex > 0u) {
_SEGGER_RTT.aDown[BufferIndex].sName = sName;
_SEGGER_RTT.aDown[BufferIndex].pBuffer = (char*)pBuffer;
_SEGGER_RTT.aDown[BufferIndex].SizeOfBuffer = BufferSize;
_SEGGER_RTT.aDown[BufferIndex].RdOff = 0u;
_SEGGER_RTT.aDown[BufferIndex].WrOff = 0u;
}
_SEGGER_RTT.aDown[BufferIndex].Flags = Flags;
SEGGER_RTT_UNLOCK();
r = 0;
} else {
r = -1;
}
return r;
}
/*********************************************************************
*
* SEGGER_RTT_TerminalOut
*
* Function description
* Writes a string to the given terminal
* without changing the terminal for channel 0.
*
* Parameters
* TerminalId Index of the terminal.
* s String to be printed on the terminal.
*
* Return value
* >= 0 - Number of bytes written.
* < 0 - Error.
*
*/
int SEGGER_RTT_TerminalOut (char TerminalId, const char* s) {
int Status;
unsigned FragLen;
unsigned Avail;
SEGGER_RTT_BUFFER_UP* pRing;
//
INIT();
//
// Validate terminal ID.
//
if (TerminalId < (char)sizeof(_aTerminalId)) { // We only support a certain number of channels
//
// Get "to-host" ring buffer.
//
pRing = &_SEGGER_RTT.aUp[0];
//
// Need to be able to change terminal, write data, change back.
// Compute the fixed and variable sizes.
//
FragLen = strlen(s);
//
// How we output depends upon the mode...
//
SEGGER_RTT_LOCK();
Avail = _GetAvailWriteSpace(pRing);
switch (pRing->Flags & SEGGER_RTT_MODE_MASK) {
case SEGGER_RTT_MODE_NO_BLOCK_SKIP:
//
// If we are in skip mode and there is no space for the whole
// of this output, don't bother switching terminals at all.
//
if (Avail < (FragLen + 4u)) {
Status = 0;
} else {
_PostTerminalSwitch(pRing, TerminalId);
Status = (int)_WriteBlocking(pRing, s, FragLen);
_PostTerminalSwitch(pRing, _ActiveTerminal);
}
break;
case SEGGER_RTT_MODE_NO_BLOCK_TRIM:
//
// If we are in trim mode and there is not enough space for everything,
// trim the output but always include the terminal switch. If no room
// for terminal switch, skip that totally.
//
if (Avail < 4u) {
Status = -1;
} else {
_PostTerminalSwitch(pRing, TerminalId);
Status = (int)_WriteBlocking(pRing, s, (FragLen < (Avail - 4u)) ? FragLen : (Avail - 4u));
_PostTerminalSwitch(pRing, _ActiveTerminal);
}
break;
case SEGGER_RTT_MODE_BLOCK_IF_FIFO_FULL:
//
// If we are in blocking mode, output everything.
//
_PostTerminalSwitch(pRing, TerminalId);
Status = (int)_WriteBlocking(pRing, s, FragLen);
_PostTerminalSwitch(pRing, _ActiveTerminal);
break;
default:
Status = -1;
break;
}
//
// Finish up.
//
SEGGER_RTT_UNLOCK();
} else {
Status = -1;
}
return Status;
}
/*********************************************************************
*
* SEGGER_RTT_Write
*
* Function description
* Stores a specified number of characters in SEGGER RTT
* control block which is then read by the host.
*
* Parameters
* BufferIndex Index of "Up"-buffer to be used. (e.g. 0 for "Terminal")
* pBuffer Pointer to character array. Does not need to point to a \0 terminated string.
* NumBytes Number of bytes to be stored in the SEGGER RTT control block.
*
* Return values
* Number of bytes which have been stored in the "Up"-buffer.
*
* Notes
* (1) If there is not enough space in the "Up"-buffer, remaining characters of pBuffer are dropped.
*/
int32_t SEGGER_RTT_Write(unsigned BufferIndex, const char* pBuffer, unsigned NumBytes) {
int32_t NumBytesToWrite;
unsigned NumBytesWritten;
int32_t RdOff;
//
// Target is not allowed to perform other RTT operations while string still has not been stored completely.
// Otherwise we would probably end up with a mixed string in the buffer.
//
SEGGER_RTT_LOCK();
_Init();
//
// In case we are not in blocking mode,
// we need to calculate, how many bytes we can put into the buffer at all.
//
if ((_SEGGER_RTT.aUp[BufferIndex].Flags & SEGGER_RTT_MODE_MASK) != SEGGER_RTT_MODE_BLOCK_IF_FIFO_FULL) {
RdOff = _SEGGER_RTT.aUp[BufferIndex].RdOff;
NumBytesToWrite = RdOff - _SEGGER_RTT.aUp[BufferIndex].WrOff - 1;
if (NumBytesToWrite < 0) {
NumBytesToWrite += _SEGGER_RTT.aUp[BufferIndex].SizeOfBuffer;
}
//
// If the complete data does not fit in the buffer, check if we have to skip it completely or trim the data
//
if ((int32_t)NumBytes > NumBytesToWrite) {
if ((_SEGGER_RTT.aUp[BufferIndex].Flags & SEGGER_RTT_MODE_MASK) == SEGGER_RTT_MODE_NO_BLOCK_SKIP) {
SEGGER_RTT_UNLOCK();
return 0;
} else {
NumBytes = NumBytesToWrite;
}
}
}
//
// Early out if nothing is to do
//
if (NumBytes == 0) {
SEGGER_RTT_UNLOCK();
return 0;
}
//
// Write data to buffer and handle wrap-around if necessary
//
NumBytesWritten = 0;
do {
RdOff = _SEGGER_RTT.aUp[BufferIndex].RdOff; // May be changed by host (debug probe) in the meantime
NumBytesToWrite = RdOff - _SEGGER_RTT.aUp[BufferIndex].WrOff - 1;
if (NumBytesToWrite < 0) {
NumBytesToWrite += _SEGGER_RTT.aUp[BufferIndex].SizeOfBuffer;
}
NumBytesToWrite = MIN(NumBytesToWrite, (_SEGGER_RTT.aUp[BufferIndex].SizeOfBuffer - _SEGGER_RTT.aUp[BufferIndex].WrOff)); // Number of bytes that can be written until buffer wrap-around
NumBytesToWrite = MIN(NumBytesToWrite, (int32_t)NumBytes);
MEMCPY(_SEGGER_RTT.aUp[BufferIndex].pBuffer + _SEGGER_RTT.aUp[BufferIndex].WrOff, pBuffer, NumBytesToWrite);
NumBytesWritten += NumBytesToWrite;
pBuffer += NumBytesToWrite;
NumBytes -= NumBytesToWrite;
_SEGGER_RTT.aUp[BufferIndex].WrOff += NumBytesToWrite;
if (_SEGGER_RTT.aUp[BufferIndex].WrOff == _SEGGER_RTT.aUp[BufferIndex].SizeOfBuffer) {
_SEGGER_RTT.aUp[BufferIndex].WrOff = 0;
}
} while (NumBytes);
SEGGER_RTT_UNLOCK();
return NumBytesWritten;
}
