Документация

classdef DebugIOToolTemplate < target.DebugIOTool
% DEBUGIOTOOLTEMPLATE Example implementation of target.DebugIOTool
% debugger abstraction.

%   Copyright 2020 The MathWorks, Inc.
    
    properties (Access=private)
        
        % Optional
        % Add any state required to interact with the debugger or
        % application being run in the debugger as a property of
        % DebugIOTool. Apply private access so that only this file 
        % can access the state.
        %
        % For example, the state could be a handle to the debugger
        % application provided by the debugger external API.
        DebuggerHandle;
    end   
    
    % Method implementations that perform debugger interactions.
    % Each method will return a 'withoutError' logical flag indicating 
    % whether the method executed withoutError. Consider also using the 
    % MATLAB error method to report custom error information.
    methods
                
        % Constructor for the target.DebugIOTool. The constructor
        % creates an instance of the tool allowing its methods to be called
        % on that instance. Optional.
        function this = DebugIOToolTemplate()
            
            % Basic initialization can be performed here. For example
            % setting state ready for calls to open
        end
        
        % Open the debugger. Optional.
        function withoutError = open(this)
            
            % Add logic here to open the debugger. Typically, use system
            % commands or the external API provided by the debugger.
            %
            % If you cannot open the debugger without also loading the
            % application into the debugger, this method should not be
            % implemented and the logic should be performed in the
            % 'loadApplication' method.
            %
            % If you cannot open the debugger without also starting
            % execution of the application, this method should not be
            % implemented and the logic should be performed in the
            % 'startApplication' method.
            
            this.DebuggerHandle = this.callExternalDebugger('open');
            withoutError = true;
        end
        
        % Load the application into the debugger. Optional.
        function withoutError = loadApplication(this)
            
            % Add logic here to load the application into the debugger.
            % This could be loading a project into an IDE debugger or
            % loading the application executable into the debugger harness.
            %
            % Additionally add logic to set breakpoints in the debugger to
            % break execution.
            %
            % The path to the application to load is stored in the
            % Application property of this class which can be accessed
            % using this.Application in this method.
            %
            % Additional command line arguments to pass to the the 
            % application are stored in 
            % this.ApplicationCommandLineArguments.
            %
            % Breakpoints to set are stored in this.Breakpoints
            %            
            % If you cannot load the application without also starting
            % execution of the application, this method should not be
            % implemented and the logic should be performed in the
            % 'startApplication' method.
            
            this.callExternalDebugger('load application', ...
                                       this.Application, ....
                                       this.ApplicationCommandLineArguments);
            
            this.callExternalDebugger('set breakpoints', this.Breakpoints);
            
            withoutError = true;
        end
        
        % Start the application execution in the debugger. Required.
        function withoutError = startApplication(this)
            
            % Add logic here to start the application execution in the 
            % debugger.
            %
            % The path to the application to load is stored in the
            % Application property of this class which can be accessed
            % using this.Application in this method.
            %
            % Additional command line arguments to pass to the 
            % application are stored in 
            % this.ApplicationCommandLineArguments.
            %
            % Breakpoints to set are stored in this.Breakpoints
            
            this.callExternalDebugger('start application');
            
            withoutError = true;
        end
        
        % Stop the application execution in the debugger. Optional.
        function withoutError = stopApplication(this)
                        
            % Add logic here to stop the application execution in the 
            % debugger.
            
            % If your 'startApplication' method opened the debugger,
            % perform the opposite action here, i.e. close the 
            % debugger.
            %
            % If your 'startApplication' method loaded the application,
            % perform the opposite action here, i.e. unload the
            % application from the debugger.
            
            this.callExternalDebugger('stop application');
            
            withoutError = true;
        end
        
        % Unloads the application from the debugger. Optional.
        function withoutError = unloadApplication(this)
                        
            % If you implemented the 'loadApplication' method, 
            % then add logic here to unload the application from
            % the debugger.
            
            % If your 'loadApplication' method opened the debugger, 
            % perform the opposite action here, i.e. close the 
            % debugger.
            
            this.callExternalDebugger('unload application');
            
            withoutError = true;
        end
        
        % Closes the debugger. Optional.
        function withoutError = close(this)
                        
            % Add logic here to close the debugger. If you implemented the 
            % 'open' method you should implement this method.
            
            this.callExternalDebugger('close');
            
            withoutError = true;
        end              
        
        % Asks if the debugger is currently stopped at the specified
        % breakpoint. Returns true if at the specified breakpoint, false
        % otherwise. Required.
        function [atBreakpoint, withoutError] = ...
                                    stoppedAtBreakpoint(this, breakpoint)
            
            % Add logic to determine if the debugger has broken execution
            % at the breakpoint passed into the function.
            %
            % The 'breakpoint' input variable is of type target.Breakpoint 
            % which provides the description of the breakpoint. It contains
            % properties Function, File and Line which describes the
            % location of the breakpoint.
            %
            % Set the atBreakpoint return value to true if the debugger is
            % stopped at the breakpoint, or false if not.
            
            result = this.callExternalDebugger('determine breakpoint hit', ...
                                                breakpoint.File, ...
                                                breakpoint.Line, ...
                                                breakpoint.Function);
            atBreakpoint = ~isempty(result);
            
            withoutError = true;
        end
        
        % Continues execution if application execution is paused in the 
        % debugger. Required.
        function withoutError = continueExecution(this)
            
            this.callExternalDebugger('continue execution');
            withoutError = true;
        end  
                
        % Write the specified memory stream to the target platform memory
        % specified by the given variable name.
        function withoutError = write(this, variableName, memoryStream)
            
            % Add logic to write the memoryStream data to the variableName
            % variable in the target. This function should assume that the
            % appropriate breakpoint has been hit to perform such an
            % action.
            %
            % memoryStream is a vector of uint64 values to be written to
            % the target platform. The unit64 values act as a container for
            % the smallest addressable integer on the target platform. In
            % most cases this will be a container for the size of char on
            % the target platform, which will commonly be 8-bit.
            %
            % The specified variable will represent a pointer to the
            % smallest addressable integer type.
            
            % As an example write operations on a target platform where 
            % char represents the smallest addressable integer should be 
            % equivilant to the following memcpy call in C code:
            %
            % (void*)memcpy(<variableName>, ...
                            (unsigned char[<sizeOfMemoryStream>]) ...
                            {<memoryStream(1)>,<memoryStream(2)>, ...}, ...
                            <sizeOfMemoryStream>);
            %
            % A lot of debuggers allow for immediate execution of code when
            % execution is broken, if so, attempt to use the above command
            % to write data to the variable like the below example:
              
            sizeOfMemoryVariable = uint64(numel(memoryStream));
            arrayFormat = repmat('%d,', [1 sizeOfMemoryVariable]);
            arrayFormat(end) = [];
              
            this.callExternalDebugger(sprintf('execute (void*)memcpy(%s, ...
                                      (unsigned char [%d]){%s}, %d)', ...
                                      variableName, ...
                                      sizeOfMemoryVariable, ...
                                      sprintf(arrayFormat, memoryStream), ...
                                      sizeOfMemoryVariable));
                          
            withoutError = true;
        end
        
        % read the memory stream from the target platform memory specified 
        % by the given variable name.
        function [memoryStream, withoutError] = read(this, ...
                                                     variableName, ...
                                                     sizeToRead)            
            
            % Add logic to read from the variableName variable on the 
            % target. This function should assume that the appropriate 
            % breakpoint has been hit to perform such an action.
            %
            % The memoryStream return value should be a vector of uint64 
            % values. The unit64 values act as a container for the smallest 
            % addressable integer on the target platform. In most cases 
            % this will be a container for the size of char on the target 
            % platform, which will commonly be 8-bit.
            %
            % The specified variable will represent a pointer to the
            % smallest addressable integer type.
            
            % Read operations should be equivilant to inspecting the result
            % of the following C code:
            % (unsigned char [<sizeToRead>])*<variableName>
            %
            % A lot of debuggers allow for immediate execution of code when
            % execution is broken, if so, attempt to use the above command
            % to inspect the value of the buffer and return it to MATLAB.
                        
            memoryStream = this.callExternalDebugger(...
                           sprintf("read (unsigned char [%d])*%s", ...
                           sizeToRead, variableName));
            
            % The memory stream must be returned as a vector of uint64
            % values
            memoryStream = uint64(memoryStream);
            
            withoutError = true;
        end
    end
    
    methods (Access=private)
        
        function output = callExternalDebugger(~, varargin)
            
            output = [];
            fprintf("\nInstructed the debugger to '%s'\n", varargin{1});
            
            if nargin > 2
                disp('Using arguments:');
                disp(varargin(2:end));
            end
        end
    end
end