From patchwork Thu Sep 28 17:15:26 2017 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: David Malcolm X-Patchwork-Id: 819690 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=pass (mailfrom) smtp.mailfrom=gcc.gnu.org (client-ip=209.132.180.131; helo=sourceware.org; envelope-from=gcc-patches-return-463124-incoming=patchwork.ozlabs.org@gcc.gnu.org; receiver=) Authentication-Results: ozlabs.org; dkim=pass (1024-bit key; unprotected) header.d=gcc.gnu.org header.i=@gcc.gnu.org header.b="KGHoOG9I"; dkim-atps=neutral Received: from sourceware.org (server1.sourceware.org [209.132.180.131]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 3y31YG606qz9sRq for ; Fri, 29 Sep 2017 03:15:45 +1000 (AEST) DomainKey-Signature: a=rsa-sha1; c=nofws; d=gcc.gnu.org; h=list-id :list-unsubscribe:list-archive:list-post:list-help:sender:from :to:cc:subject:date:message-id:in-reply-to:references; q=dns; s= default; b=G3PL6jU4mTvy9ir2JlGAD2fb6/+Ywdoq7efcYayP1OGXFRxy8ZHzQ bk5GN6JdxPSC7dVA+RlaG2EeG5hH8uWwdZEQhf+FnUvUTvkZNWPnuwnsgPfbMTHe nodi27JCFbCmdfEOElU98ejaYSKCI8xAfbNAEranadMmz+kFlNAf9s= DKIM-Signature: v=1; a=rsa-sha1; c=relaxed; d=gcc.gnu.org; h=list-id :list-unsubscribe:list-archive:list-post:list-help:sender:from :to:cc:subject:date:message-id:in-reply-to:references; s= default; bh=uTGW0Yr9OhJTfEQYZKVdtnIj244=; b=KGHoOG9I+pYClmhhdqHG l+pLPhTNdm/exw5Np6SIQu2BUBwjmVE07cR9Oe4EazeeKp/pPa2PtobVChh8dxJj dyXdhikUxJZ4mMXBS2PbwcxqudCPeSqPjAB3pZqkqaHsaVjZwU07L6Zj/L/CggLs 6LXHNKaz6w3HShe6yDv1/7A= Received: (qmail 60806 invoked by alias); 28 Sep 2017 17:15:28 -0000 Mailing-List: contact gcc-patches-help@gcc.gnu.org; run by ezmlm Precedence: bulk List-Id: List-Unsubscribe: List-Archive: List-Post: List-Help: Sender: gcc-patches-owner@gcc.gnu.org Delivered-To: mailing list gcc-patches@gcc.gnu.org Received: (qmail 60704 invoked by uid 89); 28 Sep 2017 17:15:20 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-25.9 required=5.0 tests=BAYES_00, GIT_PATCH_0, GIT_PATCH_1, GIT_PATCH_2, GIT_PATCH_3, KAM_LAZY_DOMAIN_SECURITY, RP_MATCHES_RCVD, SPF_HELO_PASS autolearn=ham version=3.3.2 spammy=cs, Quote 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 ESMTP; Thu, 28 Sep 2017 17:15:15 +0000 Received: from smtp.corp.redhat.com (int-mx04.intmail.prod.int.phx2.redhat.com [10.5.11.14]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id 950FC16FABB; Thu, 28 Sep 2017 17:15:13 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.3.2 mx1.redhat.com 950FC16FABB Authentication-Results: ext-mx06.extmail.prod.ext.phx2.redhat.com; dmarc=none (p=none dis=none) header.from=redhat.com Authentication-Results: ext-mx06.extmail.prod.ext.phx2.redhat.com; spf=fail smtp.mailfrom=dmalcolm@redhat.com Received: from c64.redhat.com (ovpn-112-11.phx2.redhat.com [10.3.112.11]) by smtp.corp.redhat.com (Postfix) with ESMTP id 6B198179DE; Thu, 28 Sep 2017 17:15:12 +0000 (UTC) From: David Malcolm To: jit@gcc.gnu.org, gcc-patches@gcc.gnu.org Cc: David Malcolm Subject: [committed] jit: document function pointers Date: Thu, 28 Sep 2017 13:15:26 -0400 Message-Id: <1506618926-602-1-git-send-email-dmalcolm@redhat.com> In-Reply-To: <1506018592.10251.23.camel@redhat.com> References: <1506018592.10251.23.camel@redhat.com> X-IsSubscribed: yes This patch adds a new function-pointers.rst topic page to the libgccjit docs. Committed to trunk as r253257. gcc/jit/ChangeLog: * docs/topics/expressions.rst (Function calls): Add link to gcc_jit_context_new_function_ptr_type. (Function pointers): Convert to cross-references to function-pointers.rst, moving material there. * docs/topics/function-pointers.rst: New page. * docs/topics/index.rst: Add function-pointers.rst. * docs/topics/types.rst (Function pointer types): New section. * docs/_build/texinfo/libgccjit.texi: Regenerate. --- gcc/jit/docs/topics/expressions.rst | 21 ++++---- gcc/jit/docs/topics/function-pointers.rst | 80 +++++++++++++++++++++++++++++++ gcc/jit/docs/topics/index.rst | 1 + gcc/jit/docs/topics/types.rst | 6 +++ 4 files changed, 96 insertions(+), 12 deletions(-) create mode 100644 gcc/jit/docs/topics/function-pointers.rst diff --git a/gcc/jit/docs/topics/expressions.rst b/gcc/jit/docs/topics/expressions.rst index f5c2d0f..76aa4eb 100644 --- a/gcc/jit/docs/topics/expressions.rst +++ b/gcc/jit/docs/topics/expressions.rst @@ -416,7 +416,8 @@ Function calls int numargs, \ gcc_jit_rvalue **args) - Given an rvalue of function pointer type, and the given table of + Given an rvalue of function pointer type (e.g. from + :c:func:`gcc_jit_context_new_function_ptr_type`), and the given table of argument rvalues, construct a call to the function pointer, with the result as an rvalue. @@ -452,19 +453,15 @@ Function calls Function pointers ***************** -.. function:: gcc_jit_rvalue *\ - gcc_jit_function_get_address (gcc_jit_function *fn,\ - gcc_jit_location *loc) - - Get the address of a function as an rvalue, of function pointer - type. +Function pointers can be obtained: - This entrypoint was added in :ref:`LIBGCCJIT_ABI_9`; you can test - for its presence using - - .. code-block:: c + * from a :c:type:`gcc_jit_function` using + :c:func:`gcc_jit_function_get_address`, or - #ifdef LIBGCCJIT_HAVE_gcc_jit_function_get_address + * from an existing function using + :c:func:`gcc_jit_context_new_rvalue_from_ptr`, + using a function pointer type obtained using + :c:func:`gcc_jit_context_new_function_ptr_type`. Type-coercion ************* diff --git a/gcc/jit/docs/topics/function-pointers.rst b/gcc/jit/docs/topics/function-pointers.rst new file mode 100644 index 0000000..b5b9d1b --- /dev/null +++ b/gcc/jit/docs/topics/function-pointers.rst @@ -0,0 +1,80 @@ +.. Copyright (C) 2017 Free Software Foundation, Inc. + Originally contributed by David Malcolm + + This is free software: you can redistribute it and/or modify it + under the terms of the GNU General Public License as published by + the Free Software Foundation, either version 3 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see + . + +.. default-domain:: c + +Function pointers +================= + +You can generate calls that use a function pointer via +:c:func:`gcc_jit_context_new_call_through_ptr`. + +To do requires a :c:type:`gcc_jit_rvalue` of the correct function pointer type. + +Function pointers for a :c:type:`gcc_jit_function` can be obtained +via :c:func:`gcc_jit_function_get_address`. + +.. function:: gcc_jit_rvalue *\ + gcc_jit_function_get_address (gcc_jit_function *fn,\ + gcc_jit_location *loc) + + Get the address of a function as an rvalue, of function pointer + type. + + This entrypoint was added in :ref:`LIBGCCJIT_ABI_9`; you can test + for its presence using + + .. code-block:: c + + #ifdef LIBGCCJIT_HAVE_gcc_jit_function_get_address + +Alternatively, given an existing function, you can obtain a pointer +to it in :c:type:`gcc_jit_rvalue` form using +:c:func:`gcc_jit_context_new_rvalue_from_ptr`, using a function pointer +type obtained using :c:func:`gcc_jit_context_new_function_ptr_type`. + +Here's an example of creating a function pointer type corresponding to C's +:c:type:`void (*) (int, int, int)`: + +.. code-block:: c + + gcc_jit_type *void_type = + gcc_jit_context_get_type (ctxt, GCC_JIT_TYPE_VOID); + gcc_jit_type *int_type = + gcc_jit_context_get_type (ctxt, GCC_JIT_TYPE_INT); + + /* Build the function ptr type. */ + gcc_jit_type *param_types[3]; + param_types[0] = int_type; + param_types[1] = int_type; + param_types[2] = int_type; + + gcc_jit_type *fn_ptr_type = + gcc_jit_context_new_function_ptr_type (ctxt, NULL, + void_type, + 3, param_types, 0); + +.. function:: gcc_jit_type *\ + gcc_jit_context_new_function_ptr_type (gcc_jit_context *ctxt,\ + gcc_jit_location *loc,\ + gcc_jit_type *return_type,\ + int num_params,\ + gcc_jit_type **param_types,\ + int is_variadic) + + Generate a :c:type:`gcc_jit_type` for a function pointer with the + given return type and parameters. diff --git a/gcc/jit/docs/topics/index.rst b/gcc/jit/docs/topics/index.rst index 890f21c..a912a6d 100644 --- a/gcc/jit/docs/topics/index.rst +++ b/gcc/jit/docs/topics/index.rst @@ -26,6 +26,7 @@ Topic Reference types.rst expressions.rst functions.rst + function-pointers.rst locations.rst compilation.rst compatibility.rst diff --git a/gcc/jit/docs/topics/types.rst b/gcc/jit/docs/topics/types.rst index c279222..35a8231 100644 --- a/gcc/jit/docs/topics/types.rst +++ b/gcc/jit/docs/topics/types.rst @@ -309,3 +309,9 @@ You can model C `struct` types by creating :c:type:`gcc_jit_struct *` and :start-after: /* Quote from here in docs/topics/types.rst. */ :end-before: /* Quote up to here in docs/topics/types.rst. */ :language: c + +Function pointer types +---------------------- + +Function pointer types can be created using +:c:func:`gcc_jit_context_new_function_ptr_type`.