1
0
Fork 0
mirror of https://github.com/eclipse-cdt/cdt synced 2025-07-24 01:15:29 +02:00

Updated to provide clarity on the use of TEMPORARY as a special-case, bit-wise qualifier.

This commit is contained in:
John Cortell 2008-05-06 21:01:02 +00:00
parent 3f5cccb36d
commit 1f35172785

View file

@ -15,24 +15,29 @@ import org.eclipse.core.runtime.CoreException;
public interface ICBreakpointTyped {
/**
* Breakpoint attribute storing the type this breakpoint
* is set in (value <code>"org.eclipse.cdt.debug.core.type"</code>).
* This attribute is a <code>int</code>.
* Possible values are
* <code>ICBreakpointTyped.REGULAR</code>
* <code>ICBreakpointTyped.HARDWARE</code>
* <code>ICBreakpointTyped.TEMPORARY</code>
* Breakpoint attribute storing the type of the breakpoint
* This attribute is a <code>int</code>. Strictly speaking,
* types are even values, but the least-significant bit
* is used to qualify it as temporary. See {@link #TEMPORARY}
*
* @since 5.0
*/
public static final String TYPE = "org.eclipse.cdt.debug.core.breakpointType"; //$NON-NLS-1$
/**
* This type of breakpoint is exposed to the user. How it is installed
* (hardware or software) is up to the discretion of the debugger backend. A
* common backend approach is to try one way first and then the other if the
* first attempt fails.
* A bit-wise qualifier (the only one); not a type in and of itself. All
* types are even values (including zero). The least significant bit can be
* turned on to further qualify the breakpoint as a one that the user
* doesn't see. It is typically installed programatically by the debugger,
* hit once and then uninstalled.
*/
final static public int TEMPORARY = 0x1;
/**
* A REGULAR breakpoint is a line, function or address breakpoint whose
* installation mechanism (hardware vs software) is up to the discretion of
* the debugger backend A common backend approach is to try one way first
* and then the other if the first attempt fails.
*
* <p>
* In the future, we will expose a preference that lets the user dictate his
@ -43,84 +48,55 @@ public interface ICBreakpointTyped {
* <p>
* It's important to realize that how a backend ends up installing the
* breakpoint does not alter the type of the breakpoint in the Eclipse/CDT
* layer. A regular breakpoint will always be a <i>regular</i> breakpoint
* layer. A REGULAR breakpoint will always be a <i>REGULAR</i> breakpoint
* regardless of the technique the backend used to install it (software or
* hardware).
*/
final static public int REGULAR = 0x0;
final static public int REGULAR = 0x0 << 1;
/**
* This type of breakpoint is <b>not</b> exposed to the user and is
* typically uninstalled after getting hit. How it is installed (hardware or
* software) is up to the discretion of the debugger backend. A common
* backend approach is to try one way first and then the other if the first
* attempt fails.
* A HARDWARE breakpoint is a line, function or address breakpoint that the
* user wants installed using a hardware breakpoint facility on the target.
* If it cannot be installed that way, it should not be installed at all.
*
* <p>
* Unlike the <i>regular</i> breakpoint type, there are no plans to let the
* user coax the backend to install a temporary breakpoint in any particular
* way (hardware vs software).
* For example, the hardware may have a breakpoint register where an address
* can be set. The target will halt itself when the PC matches that register
* value. Hardware breakpoints have several advantages. They're
* non-intrusive to the code and so are simpler for the debugger to
* install/uninstall/manage. Also, because they are non-intrusive, they
* allow for breakpoints to be set in ROM code. The disadvantage is that
* support for them is often limited. Some architectures only support one or
* two hardware breakpoints.
*/
final static public int TEMPORARY = 0x1;
final static public int HARDWARE = 0x1 << 1;
/**
* This type of breakpoint is exposed to the user. The user intends for the
* breakpoint to be installed as a hardware breakpoint and if it cannot be
* installed as such it should not be installed at all.
* A SOFTWARE breakpoint is a line, function or address breakpoint that the
* user wants installed by swapping out instructions in the target code
* memory with an opcode that causes the target to halt. If it cannot be
* installed that way, it should not be installed at all.
*
* A hardware breakpoint is one that makes use of a breakpoint hardware
* facility on the target. For example, the hardware may have a breakpoint
* register where an address can be set. The target will halt itself when
* the PC matches that register value. Hardware breakpoints have several
* advantages. They're non-intrusive to the code and so are simpler for the
* debugger to install/uninstall/manage. Also, because they are
* non-intrusive, they allow for breakpoints to be set in ROM code. The
* disadvantage is that support for them is often limited. Some
* architectures only support one or two hardware breakpoints.
*/
final static public int HARDWARE = 0x2;
/**
* This type of breakpoint is exposed to the user. The user intends for the
* breakpoint to be installed as a software breakpoint and if it cannot be
* installed as such it should not be installed at all.
*
* A software breakpoint is one that swaps out instructions in the target
* code memory with an opcode that causes the target to halt. The only
* advantage to software breakpoints is that there is no limit to how many
* can be set. The disadvantages are that they are intrusive and thus more
* difficult to install/uninstall/manage and, of course, they can't be set
* in ROM code.
* The only advantage to software breakpoints is that there is no limit to
* how many can be set. The disadvantages are that they are intrusive and
* thus more difficult to install/uninstall/manage and, of course, they
* can't be set in ROM code.
*
*/
final static public int SOFTWARE = 0x4;
/**
* This type of breakpoint is <b>not</b> exposed to the user. The code that
* creates such a breakpoint intends for the breakpoint to be installed as a
* hardware breakpoint and if it cannot be installed as such it should not
* be installed at all.
*
*/
final static public int TEMPORARY_HARDWARE = TEMPORARY | HARDWARE;
/**
* This type of breakpoint is <b>not</b> exposed to the user. The code that
* creates such a breakpoint intends for the breakpoint to be installed as a
* software breakpoint and if it cannot be installed as such it should not
* be installed at all.
*
*/
final static public int TEMPORARY_SOFTWARE = TEMPORARY | SOFTWARE;
final static public int SOFTWARE = 0x2 << 1;
// ------------------------------------------------------------------------
// ALL FUTURE ADDITIONS MUST HAVE EVEN VALUES. The lease-significant
// bit is reserved.
// ------------------------------------------------------------------------
/**
* Returns the type of this breakpoint
*
* @return type of breakpoint. Defaults to REGULAR if property does not exists in
* the underlying marker.
* @exception CoreException if unable to access the property on this breakpoint's
* underlying marker
* @return type of breakpoint. Defaults to REGULAR if property does not
* exists in the underlying marker.
* @exception CoreException
* if unable to access the property on this breakpoint's
* underlying marker
*
* @since 5.0
*/
@ -129,11 +105,13 @@ public interface ICBreakpointTyped {
/**
* Sets the type of this breakpoint.
*
* @param type breakpoint type
* @exception CoreException if unable to access the property on this breakpoint's
* underlying marker
*
* @since 5.0
* @param type
* breakpoint type
* @exception CoreException
* if unable to access the property on this breakpoint's
* underlying marker
*
* @since 5.0
*/
public void setType( int type ) throws CoreException;
}