| Message ID | 1393901250-3922-2-git-send-email-xbing6@gmail.com |
|---|---|
| State | New |
| Headers | show |
On Tue, Mar 04, 2014 at 10:47:21AM +0800, Xuebing Wang wrote: > Signed-off-by: Xuebing Wang <xbing6@gmail.com> > --- > docs/api-hierarchy.txt | 93 ++++++++++++++++++++++++++++++++++++++++++++++++ > 1 file changed, 93 insertions(+) > create mode 100644 docs/api-hierarchy.txt This type of documentation gets outdated really quickly. I'm not sure it should be merged. Documenting the various APIs as doc comments in the code would have a better chance of staying up-to-date.
On 03/04/2014 05:42 PM, Stefan Hajnoczi wrote: > On Tue, Mar 04, 2014 at 10:47:21AM +0800, Xuebing Wang wrote: >> Signed-off-by: Xuebing Wang <xbing6@gmail.com> >> --- >> docs/api-hierarchy.txt | 93 ++++++++++++++++++++++++++++++++++++++++++++++++ >> 1 file changed, 93 insertions(+) >> create mode 100644 docs/api-hierarchy.txt > This type of documentation gets outdated really quickly. I'm not sure > it should be merged. > > Documenting the various APIs as doc comments in the code would have a > better chance of staying up-to-date. > Thanks. But, doc comments in the code don't show the hierarchy and their dependencies (or inheriting relationship). Any idea how to draw the hierarchy to show the big picture of the APIs (as a high-level API design doc)? :-)
On Tue, Mar 04, 2014 at 05:58:13PM +0800, Xuebing wang wrote: > > On 03/04/2014 05:42 PM, Stefan Hajnoczi wrote: > >On Tue, Mar 04, 2014 at 10:47:21AM +0800, Xuebing Wang wrote: > >>Signed-off-by: Xuebing Wang <xbing6@gmail.com> > >>--- > >> docs/api-hierarchy.txt | 93 ++++++++++++++++++++++++++++++++++++++++++++++++ > >> 1 file changed, 93 insertions(+) > >> create mode 100644 docs/api-hierarchy.txt > >This type of documentation gets outdated really quickly. I'm not sure > >it should be merged. > > > >Documenting the various APIs as doc comments in the code would have a > >better chance of staying up-to-date. > > > > Thanks. But, doc comments in the code don't show the hierarchy and > their dependencies (or inheriting relationship). > > Any idea how to draw the hierarchy to show the big picture of the > APIs (as a high-level API design doc)? :-) We do have high-level documentation for specific modules. For example, see include/qom/object.h. It documents more than just individual functions. So if you want to find out about QEMU Object Model, then object.h has the documentation you need to get the big picture *and* understand the APIs. The relationships between modules are a different issue. I don't think it's worth trying to document them because they will get out of date. What's worse than no documentation? Incorrect documentation. QEMU does not have a stable API, things can change at any time. This has many benefits but also the drawback that documentation gets outdated quickly. I don't think it's a good idea to give the impression that things are stable when they are not. In other words, module-level documentation is good but high-level API design doesn't exist because we don't have a stable API.
diff --git a/docs/api-hierarchy.txt b/docs/api-hierarchy.txt new file mode 100644 index 0000000..9982f51 --- /dev/null +++ b/docs/api-hierarchy.txt @@ -0,0 +1,93 @@ +API hierarchy +============= + +1) QEMU common API + + |-------------------------------| + | C99 API | + | - <stdio.h> <stdlib.h> ... | + |-------------------------------| + | QEMU basic API | + | - include/qemu/* | + |-------------------------------| + | QEMU utility/helper API | + | - block | + | - disas | + | - migration | + | - monitor | + | - net | + | - qapi | + | - ... | + |-------------------------------| + +2) CPUArchState API + + |-----------------------------------------------------------------------| + | qom/Object | QEMU common API | + |--------------| - Linux API | + | - QEMU basic API | + | - QEMU utility/helper API | + |-----------------------------------------------------------------------| + | qdev/DeviceState | + |-----------------------------------------------------------------------| + | Create new file? | sysemu/kvm.h | hw/xen/xen.h | + | exec/cpu-exec.h? | | | + |------------------------------------------------| + | TODO: consider to abstract vcpu here? | + | include/qom/vcpu.h? | + |-----------------------------------------------------------------------| + | qom/CPUState | + |-----------------------------------------------------------------------| + | target-xxx/CPUArchState | sysemu/sysemu.h | + |-----------------------------------------------------------------------| + + cpu-exec.h is for one (tcg) of the 3 accelerators: tcg, kvm and xen. + +3) Memory API + + |--------------------------------------------------------------| + | linux-user | softmmu | + | gueust virtual address | guest physical address | + | | guest virtual address | + | | | + | | --------------------------------| + | | | Memory modelling | + | | | | + | | | MemoryRegion | RAMBlock | + | | | memory.h | | + | | --------------------------------| + | | | softmmu API | + | | | - include/exec/softmmu*.h | + | | | - include/exec/cputlb.h | + |--------------------------------------------------------------| + | memory load/store API | + | include/exec/cpu-common.h | + |--------------------------------------------------------------| + +4) exec API + + architecture-independent | architecture + | specific + |------------------| | + | memory | | + | load/store API | | + | cpu-common.h | | + |-----------------------------------------------------|---------------| + | tcg framework | tcg frontend | + | tcg/tcg*.h | | + |------------------|---------------|---------------| + | TranslationBlock | | + | translate.h | | + |-------------------------------------|---------------|---------------| + | | misc cpu API | misc cpu API | + | include/exec/exec-all.h | cpu-common.h | cpu-all.h | + |-------------------------------------|---------------|---------------| + + include/exec includes: + - Memory API + - TranslationBlock API + - misc cpu API (both architecture-independent and architecture-specific) + + include/exec/cpu-all.h is for architecture-specific, it's only included + in target-xxx/* files. +
Signed-off-by: Xuebing Wang <xbing6@gmail.com> --- docs/api-hierarchy.txt | 93 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 93 insertions(+) create mode 100644 docs/api-hierarchy.txt