From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 9898 invoked by alias); 7 Oct 2014 17:51:05 -0000 Mailing-List: contact gcc-patches-help@gcc.gnu.org; run by ezmlm Precedence: bulk List-Id: List-Archive: List-Post: List-Help: Sender: gcc-patches-owner@gcc.gnu.org Received: (qmail 9878 invoked by uid 89); 7 Oct 2014 17:51:04 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=1.9 required=5.0 tests=AWL,BAYES_00,BODY_8BITS,GARBLED_BODY,SPF_HELO_PASS,SPF_PASS,T_RP_MATCHES_RCVD autolearn=no version=3.3.2 X-Spam-User: qpsmtpd, 2 recipients X-HELO: mx1.redhat.com Received: from mx1.redhat.com (HELO mx1.redhat.com) (209.132.183.28) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with (AES256-GCM-SHA384 encrypted) ESMTPS; Tue, 07 Oct 2014 17:51:03 +0000 Received: from int-mx09.intmail.prod.int.phx2.redhat.com (int-mx09.intmail.prod.int.phx2.redhat.com [10.5.11.22]) by mx1.redhat.com (8.14.4/8.14.4) with ESMTP id s97Hp20R016846 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=FAIL); Tue, 7 Oct 2014 13:51:02 -0400 Received: from surprise.redhat.com (vpn-234-11.phx2.redhat.com [10.3.234.11]) by int-mx09.intmail.prod.int.phx2.redhat.com (8.14.4/8.14.4) with ESMTP id s97Hp1Cu012915; Tue, 7 Oct 2014 13:51:01 -0400 From: David Malcolm To: jit@gcc.gnu.org, gcc-patches@gcc.gnu.org Cc: David Malcolm Subject: =?UTF-8?q?=5Bjit=5D=20Documentation=20tweaks?= Date: Tue, 07 Oct 2014 17:51:00 -0000 Message-Id: <1412704031-27816-1-git-send-email-dmalcolm@redhat.com> MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-IsSubscribed: yes X-SW-Source: 2014-10/txt/msg00579.txt.bz2 Committed to branch dmalcolm/jit: gcc/jit/ChangeLog.jit: * docs/internals/index.rst (Overview of code structure): Directly include the comment from jit-common.h as rst, rather than as a quoted C++ comment. * jit-common.h: Convert the summary format to valid reStructured text for inclusion by docs/internals/index.rst. * notes.txt: Clarify where libgccjit.c, jit-recording.c and jit-playback.c fit into the high-level diagram. --- gcc/jit/ChangeLog.jit | 10 ++++++++++ gcc/jit/docs/internals/index.rst | 7 +++---- gcc/jit/jit-common.h | 12 +++++++----- gcc/jit/notes.txt | 13 +++++++++---- 4 files changed, 29 insertions(+), 13 deletions(-) diff --git a/gcc/jit/ChangeLog.jit b/gcc/jit/ChangeLog.jit index 4592002..1a76543 100644 --- a/gcc/jit/ChangeLog.jit +++ b/gcc/jit/ChangeLog.jit @@ -1,5 +1,15 @@ 2014-10-07 David Malcolm + * docs/internals/index.rst (Overview of code structure): Directly + include the comment from jit-common.h as rst, rather than as a + quoted C++ comment. + * jit-common.h: Convert the summary format to valid reStructured + text for inclusion by docs/internals/index.rst. + * notes.txt: Clarify where libgccjit.c, jit-recording.c and + jit-playback.c fit into the high-level diagram. + +2014-10-07 David Malcolm + * Make-lang.in (jit_OBJS): Drop jit/internal-api.o. Add jit/jit-recording.o and jit/jit-playback.o. diff --git a/gcc/jit/docs/internals/index.rst b/gcc/jit/docs/internals/index.rst index 3065c60..1e3952c 100644 --- a/gcc/jit/docs/internals/index.rst +++ b/gcc/jit/docs/internals/index.rst @@ -152,7 +152,6 @@ Overview of code structure Here is a high-level summary from ``jit-common.h``: - .. literalinclude:: ../../jit-common.h - :start-after: /* Summary. */ - :end-before: namespace gcc { - :language: c++ +.. include:: ../../jit-common.h + :start-after: This comment is included by the docs. + :end-before: End of comment for inclusion in the docs. */ diff --git a/gcc/jit/jit-common.h b/gcc/jit/jit-common.h index 5c41ddd..58e4a8c 100644 --- a/gcc/jit/jit-common.h +++ b/gcc/jit/jit-common.h @@ -36,9 +36,9 @@ along with GCC; see the file COPYING3. If not see const int NUM_GCC_JIT_TYPES = GCC_JIT_TYPE_FILE_PTR + 1; -/* Summary. */ +/* This comment is included by the docs. -/* In order to allow jit objects to be usable outside of a compile + In order to allow jit objects to be usable outside of a compile whilst working with the existing structure of GCC's code the C API is implemented in terms of a gcc::jit::recording::context, which records the calls made to it. @@ -79,15 +79,17 @@ const int NUM_GCC_JIT_TYPES = GCC_JIT_TYPE_FILE_PTR + 1; During a playback, we associate objects from the recording with their counterparts during this playback. For simplicity, we store this - within the recording objects, as "void *m_playback_obj", casting it to + within the recording objects, as ``void *m_playback_obj``, casting it to the appropriate playback object subclass. For these casts to make sense, the two class hierarchies need to have the same structure. - Note that the playback objects that "m_playback_obj" points to are + Note that the playback objects that ``m_playback_obj`` points to are GC-allocated, but the recording objects don't own references: these associations only exist within a part of the code where the GC doesn't collect, and are set back to NULL before the GC can - run. */ + run. + + End of comment for inclusion in the docs. */ namespace gcc { diff --git a/gcc/jit/notes.txt b/gcc/jit/notes.txt index 54dca8f..d337cb4 100644 --- a/gcc/jit/notes.txt +++ b/gcc/jit/notes.txt @@ -5,8 +5,13 @@ Client Code . Generated . libgccjit.so │ . . . . ──────────────────────────> . . . . │ . . - - . (record API calls) . + . . V . . + . . ──> libgccjit.c . + . . │ (error-checking). + . . │ . + . . ──> jit-recording.c + . . (record API calls) + . . <─────── . . . │ . . <─────────────────────────── . . │ . . . . @@ -27,8 +32,8 @@ Client Code . Generated . libgccjit.so . . . │ . ..........................................│..................VVVVVVVVVVVVV... . . . │ . No GC in here - . . . │ . - . . . (playback of API calls) + . . . │ jit-playback.c + . . . │ (playback of API calls) . . . ───────────────> creation of functions, . . . . types, expression trees . . . <──────────────── etc -- 1.7.11.7