[Open SoC Debug] Documentation and Web Site Update

Philipp Wagner philipp.wagner at tum.de
Fri May 20 15:08:43 CEST 2016


On 05/20/2016 02:15 PM, Stefan Wallentowitz wrote:
> On 20.05.2016 13:47, Philipp Wagner wrote:
>> - The first goal was to rewrite parts of the Overview document to make
>> it easier for people to get started with OSD.
> 
> I think we should split up the document in the real birds view, that is
> the intro and "OSD by Example" (great one!). And then the architecture
> overview as a separate doc. Then followed by the specs this would be a
> great step-by-step flow for people to get involved.

I agree; especially the last part listing all the debug modules feels a
bit out of place in this document.

I'm unsure if there is a need for an architecture overview document
which is not the specification itself (see below).

Taking it further, I imagine we'll end up (in an ideal world) with
something like:


PART 1: OVERVIEW DOCUMENTS
- Getting started with OSD: What is OSD all about? Why/when/who use it?
  - That's essentially chapters 1-3 of the current overview document
(Intro, Features & OSD By Example).
  - It's not written in "spec language", but as a "nice to read" document.
  - I think that's what others would call an "OSD Whitepaper"

- Architecture Overview
  Description of the architecture and the reasoning behind decisions.
(in the spec we then would not give reasons, but only discuss the
outcome of design decisions). I'm not sure what to prefer. What do
others think?

PART 2: SPECIFICATIONS
- OSD Architecture Specification
  - Overall architecture concepts & specs: events, debug modules, module
architecture, ...
  - Interconnect/on-chip transport
  - off-chip interface
  - interface to debug modules

- OSD Core Debug Modules Specification
  - Specification for the individual core debug modules
(CDM/CTM/STM/HIM/...)
  - Take from what's currently in the hardware repository


PART 3: IMPLEMENTER DOCUMENTS
PART 3.1 User Guides
- OSD Hardware Implementers Guide
  - Show (tutorial-like) how a hardware developer can integrate OSD into
his/her design

- OSD Software Implementer Guide
  - Show how a developer of a debug software tool can use OSD for his
purpose

PART 3.2 Reference Documentation
- OSD Hardware Implementation Documentation
  - Documentation for all the

- libopensocdebug API documentation
  most likely auto-generated from doxygen

- Host daemon (opensocdebugd) documentation


Philipp


More information about the OpenSoCDebug mailing list