[OpenOCD-devel] [PATCH]: 39b16ae COVER LETTER: about adapter rework

[<ge...@op...>]

This is an automated email from Gerrit.

Antonio Borneo (bor...@gm...) just uploaded a new patch set to Gerrit, which you can find at http://openocd.zylin.com/4890

-- gerrit

commit 39b16ae05423ec1542b244d1ef52f51698d7de5d
Author: Antonio Borneo <bor...@gm...>
Date:   Fri Feb 1 21:52:40 2019 +0100

    COVER LETTER: about adapter rework
    
    --- EMPTY COMMIT --- DO NOT MERGE --- TO BE ABANDONED ---
    
    I have put this "unusual" empty change in gerrit to try to keep
    here the eventual discussion on this patch series and avoid any
    cross-links between code approval in gerrit and discussions in
    the mailing-list OpenOCD-devel.
    
    This change-set has the main purpose of starting a clean-up of
    the struct jtag_interface. Such struct is a heritage of the
    times when JTAG was the only transport supported by OpenOCD.
    Today the struct above contains also the API for SWD transport,
    but the two transports are not well isolated and SWD code still
    uses some of the JTAG methods.
    HLA uses struct jtag_interface to initialize the interface, then
    has a completely independent struct for its API, but still the
    code of OpenOCD for HLA has to call some of the JTAG API.
    
    An initial tentative to reorg struct jtag_interface was started
    by Evan Hunter in [1], but after some discussion on the mailing
    list it did not get merged [2].
    
    The present proposal in this change-set:
    - is functional;
    - provides a good separation between the transports JTAG and SWD;
    - isolates HLA from JTAG but, to minimize the changes, it does
      not move (yet) the HLA APIs in the new struct adapter_driver;
    - proposes an example of extending the new struct adapter_driver
      to add a new driver at DAP-level.
    
    This proposal tries to be as less invasive as possible.
    For example it does not rename any files nor move code across
    files because such big changes are time consuming for review and
    potentially conflict with patches already under review in gerrit.
    Plus, before any invasive code move and rename, would be good to
    agree on this initial series and then coordinate the rename of
    files, folders, function, ... and the folder structure.
    I have started listing these points in the TODO file.
    
    The change-set is composed by a first set of commits to prepare
    the reorganization:
      1) swd: remove unused API frequency()
      2) jtag: simplify management of non-implemented handlers
      3) jtag: set default "jtag_only" to uninitialized transports
      4) helper: add bitmap helper primitives
    
    Then the real separation of SWD from JTAG. They still share the
    same struct jtag_interface, but now SWD does not need any support
    from JTAG code:
      5) swd: get rid of jtag queue to assert/deassert srst
    
    HLA code get independent from JTAG too:
      6) hla: use the new system_reset API
    
    We still have calls to jtag_execute_queue() in OpenOCD code that
    have to be removed, so make them visible at runtime and do not
    crash if the method is not anymore implemented in a non-JTAG
    adapter:
      7) jtag: print an errmsg on jtag_execute_queue() for non jtag transport
    
    After 7) we can further clean-up HLA and kitprog:
      8) hla: remove empty JTAG execute_queue method
      9) drivers/kitprog: remove unused JTAG execute_queue method
    
    Finally here is the so long waited restructure!
    The TODO file is updated on what should be the next cleanup:
      10) adapter: switch from struct jtag_interface to adapter_driver
      11) TODO: add restructuring of JTAG/adapter layer
    
    The new firmware versions of STLINK don't need HLA anymore, but
    don't provide any low level JTAG or SWD API that could fit in the
    existing struct adapter_driver. Here the struct is extended with a
    driver API at DAP level, then STLINK driver is extended to use it:
      12) arm_adi_v5: add API send_sequence() and use it
      13) adi_v5_dapdirect: add support for adapter drivers that provide DAP API
      14) stlink: add DAP direct driver
    The change 14) depends on some other stlink changes already sent
    for approval in gerrit, but out of the scope of this change-set.
    They have been rebased and inserted before this change-set.
    
    [1] http://openocd.zylin.com/943 ("adapter/interface: Cleanup of
        jtag_interface structure") - Evan Hunter
    [2] https://sourceforge.net/p/openocd/mailman/openocd-devel/thread/201...@ex...n/
    
    Change-Id: I75e327de2c37cb86cfbcbb23eac584fc04cafb96
    Signed-off-by: Antonio Borneo <bor...@gm...>

--