From patchwork Mon Mar 25 10:03:54 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Bartosz Golaszewski X-Patchwork-Id: 13601743 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from bombadil.infradead.org (bombadil.infradead.org [198.137.202.133]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id 00D91CD11DB for ; Mon, 25 Mar 2024 10:05:53 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=lists.infradead.org; s=bombadil.20210309; h=Sender: Content-Transfer-Encoding:Content-Type:List-Subscribe:List-Help:List-Post: List-Archive:List-Unsubscribe:List-Id:MIME-Version:References:In-Reply-To: Message-Id:Date:Subject:Cc:To:From:Reply-To:Content-ID:Content-Description: Resent-Date:Resent-From:Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID: List-Owner; bh=axk7z1VZ7n+jIlCzfdq1jFzWEn6V8DMUVThs0zK25hA=; b=rjdcO8DE1EcRL1 Nkqhzl2znTFSPfPNROaF9wuyXolq5OCj5mPp+QfRSkR3rwUxV0EklEccky8oHvLntkV1k0flJv55K qr4B2Kghv39g6F9Y5fa2TCRrQI3D1GZ52CmKB8zNzpawPmoT9JsB0khk7PTsuuIZR+v9KcwGwvWPr h8LLt0OSRO4qHQS0kCWFdVDDIFa5bl3aEYbrUv85LpvVEIYTbHxayh6aKm0xFl4Tvcv0cta6kwWeo vIWsLQZRmvJ8Vq5BMxTa0aDFhUPF/dD/MM9dLnWC2LczHTtjJaQHIEC1m918LbTLB8ShHgxZCL+bh 2mgu/NeGwb64BCMUGvuA==; Received: from localhost ([::1] helo=bombadil.infradead.org) by bombadil.infradead.org with esmtp (Exim 4.97.1 #2 (Red Hat Linux)) id 1rohCw-0000000GdFa-35oh; Mon, 25 Mar 2024 10:05:34 +0000 Received: from mail-lf1-x12f.google.com ([2a00:1450:4864:20::12f]) by bombadil.infradead.org with esmtps (Exim 4.97.1 #2 (Red Hat Linux)) id 1rohBh-0000000GcSj-19R4 for linux-arm-kernel@lists.infradead.org; Mon, 25 Mar 2024 10:04:20 +0000 Received: by mail-lf1-x12f.google.com with SMTP id 2adb3069b0e04-513e89d0816so5175636e87.0 for ; Mon, 25 Mar 2024 03:04:15 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=bgdev-pl.20230601.gappssmtp.com; s=20230601; t=1711361054; x=1711965854; darn=lists.infradead.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=bwbZht4rYHsS/RI3RkjDueLnk3zhqu+HloBw+ugNiVI=; b=ImPRwvj9KdbrbZlI66Jche1DWYiogOnS9o8j8SkufbD6Ysx4rgYFPQgkV5VN/WB3VM sfXOdroMTUtwng6+oKBgtCXcF2/5d+RJADhAabeT01mqJTUQec5tyVWflPFb/D1dq4lW 1HhDOrnGKBqYrIQosX9u8ns1SEr17PrPvZCyjf89dByyId+EgBazEEEMIlSky2VLy7j6 4yOpN/eapatzyiYNOCF4CnY12s57sZEYwy6mLmb5QTWdZKMoaoi0fskgUXIReNDwWzvZ lyOYd5e3j5pz8cD/zVdkytYX92kUCsJzcRv0M7GYRWAiXI0zwfmoi2IxTv9/pf2E9nVG o7cQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1711361054; x=1711965854; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=bwbZht4rYHsS/RI3RkjDueLnk3zhqu+HloBw+ugNiVI=; b=Rftw4NOsI1EcrAcP94MSkC7QFlNDFtTJDP5BbAfIzDLiQVHfB3/A62ozHfoJJlE39C qkRgRKbsN9VE5IQo1x/7Gap7Ng17Xym/oW+FnahLyC2cFVdAKQmAO9wCmT52JA3K3Ygt 7mK2YoH5dirlufqb4FbF8WGCqyzfKBj3qpryr79zhHl0qETW2p2DLWM7MzfDMIYY/OOG oCmRzK1gXXLlCE2k/1XfYlTEdghtBt+NUP/G5D+qz7pvNrsI92fgSEufqYTToHZMAAui znk7F/wZg9TMKPNOXoJKjM5gDdxgMMRR8POq+baVVbTX1xKwn7bTgaS+k7/kNRfzzQK2 0aFg== X-Forwarded-Encrypted: i=1; AJvYcCXcKCEdvDIFdLpoHiyiQUyaVw9TIXozySyo2QH1Jb7RMBuJrjzaQsEyuFHTP2Y9CdUcmbye+WjHlmiZV/ed1RvPU5l3nQml2ggNFKGbkZfgycaroro= X-Gm-Message-State: AOJu0YwknN5ip0ZnzMhLFAXyf43pc5B7L5DuhOscXeOYk1AvDR47zIaj kzXUCRyl5te8wnP5vtmLLLSziDawbdHgvYGdhprEh6BJLXc5AQ/ec9KflP32ozE= X-Google-Smtp-Source: AGHT+IHMP2uK2wz3NAx31rx5eJAUjH/6YZmMgjVGlyT85kOIpxVJPnLjJbFnQREqPfYkJzQ+ySDEBw== X-Received: by 2002:a05:6512:3e7:b0:513:d5b5:78e9 with SMTP id n7-20020a05651203e700b00513d5b578e9mr4317348lfq.26.1711361054359; Mon, 25 Mar 2024 03:04:14 -0700 (PDT) Received: from brgl-uxlite.home ([2a01:cb1d:75a:e000:861d:8b72:a859:4ce9]) by smtp.gmail.com with ESMTPSA id dv13-20020a0560000d8d00b0033e25c39ac3sm9086874wrb.80.2024.03.25.03.04.12 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 25 Mar 2024 03:04:13 -0700 (PDT) From: Bartosz Golaszewski To: Andy Gross , Bjorn Andersson , Konrad Dybcio , Elliot Berman , Krzysztof Kozlowski , Guru Das Srinagesh , Andrew Halaney , Maximilian Luz , Alex Elder , Srini Kandagatla , Arnd Bergmann Cc: linux-arm-msm@vger.kernel.org, linux-kernel@vger.kernel.org, linux-arm-kernel@lists.infradead.org, kernel@quicinc.com, Bartosz Golaszewski Subject: [PATCH v9 08/13] firmware: qcom: qseecom: convert to using the cleanup helpers Date: Mon, 25 Mar 2024 11:03:54 +0100 Message-Id: <20240325100359.17001-9-brgl@bgdev.pl> X-Mailer: git-send-email 2.40.1 In-Reply-To: <20240325100359.17001-1-brgl@bgdev.pl> References: <20240325100359.17001-1-brgl@bgdev.pl> MIME-Version: 1.0 X-CRM114-Version: 20100106-BlameMichelson ( TRE 0.8.0 (BSD) ) MR-646709E3 X-CRM114-CacheID: sfid-20240325_030417_764291_629192B4 X-CRM114-Status: GOOD ( 18.55 ) X-BeenThere: linux-arm-kernel@lists.infradead.org X-Mailman-Version: 2.1.34 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: "linux-arm-kernel" Errors-To: linux-arm-kernel-bounces+linux-arm-kernel=archiver.kernel.org@lists.infradead.org From: Bartosz Golaszewski Shrink the code by using __free() for allocations that are freed within the same functions. Signed-off-by: Bartosz Golaszewski --- .../firmware/qcom/qcom_qseecom_uefisecapp.c | 254 ++++++------------ 1 file changed, 84 insertions(+), 170 deletions(-) diff --git a/drivers/firmware/qcom/qcom_qseecom_uefisecapp.c b/drivers/firmware/qcom/qcom_qseecom_uefisecapp.c index 32188f098ef3..1f8c5efc2b5a 100644 --- a/drivers/firmware/qcom/qcom_qseecom_uefisecapp.c +++ b/drivers/firmware/qcom/qcom_qseecom_uefisecapp.c @@ -7,6 +7,7 @@ * Copyright (C) 2023 Maximilian Luz */ +#include #include #include #include @@ -272,11 +273,11 @@ static efi_status_t qsee_uefi_get_variable(struct qcuefi_client *qcuefi, const e const efi_guid_t *guid, u32 *attributes, unsigned long *data_size, void *data) { - struct qsee_req_uefi_get_variable *req_data; - struct qsee_rsp_uefi_get_variable *rsp_data; + struct qsee_req_uefi_get_variable *req_data __free(kfree) = NULL; + struct qsee_rsp_uefi_get_variable *rsp_data __free(kfree) = NULL; unsigned long buffer_size = *data_size; - efi_status_t efi_status = EFI_SUCCESS; unsigned long name_length; + efi_status_t efi_status; size_t guid_offs; size_t name_offs; size_t req_size; @@ -305,16 +306,12 @@ static efi_status_t qsee_uefi_get_variable(struct qcuefi_client *qcuefi, const e ); req_data = kzalloc(req_size, GFP_KERNEL); - if (!req_data) { - efi_status = EFI_OUT_OF_RESOURCES; - goto out; - } + if (!req_data) + return EFI_OUT_OF_RESOURCES; rsp_data = kzalloc(rsp_size, GFP_KERNEL); - if (!rsp_data) { - efi_status = EFI_OUT_OF_RESOURCES; - goto out_free_req; - } + if (!rsp_data) + return EFI_OUT_OF_RESOURCES; req_data->command_id = QSEE_CMD_UEFI_GET_VARIABLE; req_data->data_size = buffer_size; @@ -325,28 +322,20 @@ static efi_status_t qsee_uefi_get_variable(struct qcuefi_client *qcuefi, const e req_data->length = req_size; status = ucs2_strscpy(((void *)req_data) + req_data->name_offset, name, name_length); - if (status < 0) { - efi_status = EFI_INVALID_PARAMETER; - goto out_free; - } + if (status < 0) + return EFI_INVALID_PARAMETER; memcpy(((void *)req_data) + req_data->guid_offset, guid, req_data->guid_size); status = qcom_qseecom_app_send(qcuefi->client, req_data, req_size, rsp_data, rsp_size); - if (status) { - efi_status = EFI_DEVICE_ERROR; - goto out_free; - } + if (status) + return EFI_DEVICE_ERROR; - if (rsp_data->command_id != QSEE_CMD_UEFI_GET_VARIABLE) { - efi_status = EFI_DEVICE_ERROR; - goto out_free; - } + if (rsp_data->command_id != QSEE_CMD_UEFI_GET_VARIABLE) + return EFI_DEVICE_ERROR; - if (rsp_data->length < sizeof(*rsp_data)) { - efi_status = EFI_DEVICE_ERROR; - goto out_free; - } + if (rsp_data->length < sizeof(*rsp_data)) + return EFI_DEVICE_ERROR; if (rsp_data->status) { dev_dbg(qcuefi_dev(qcuefi), "%s: uefisecapp error: 0x%x\n", @@ -360,18 +349,14 @@ static efi_status_t qsee_uefi_get_variable(struct qcuefi_client *qcuefi, const e *attributes = rsp_data->attributes; } - goto out_free; + return efi_status; } - if (rsp_data->length > rsp_size) { - efi_status = EFI_DEVICE_ERROR; - goto out_free; - } + if (rsp_data->length > rsp_size) + return EFI_DEVICE_ERROR; - if (rsp_data->data_offset + rsp_data->data_size > rsp_data->length) { - efi_status = EFI_DEVICE_ERROR; - goto out_free; - } + if (rsp_data->data_offset + rsp_data->data_size > rsp_data->length) + return EFI_DEVICE_ERROR; /* * Note: We need to set attributes and data size even if the buffer is @@ -394,33 +379,23 @@ static efi_status_t qsee_uefi_get_variable(struct qcuefi_client *qcuefi, const e if (attributes) *attributes = rsp_data->attributes; - if (buffer_size == 0 && !data) { - efi_status = EFI_SUCCESS; - goto out_free; - } + if (buffer_size == 0 && !data) + return EFI_SUCCESS; - if (buffer_size < rsp_data->data_size) { - efi_status = EFI_BUFFER_TOO_SMALL; - goto out_free; - } + if (buffer_size < rsp_data->data_size) + return EFI_BUFFER_TOO_SMALL; memcpy(data, ((void *)rsp_data) + rsp_data->data_offset, rsp_data->data_size); -out_free: - kfree(rsp_data); -out_free_req: - kfree(req_data); -out: - return efi_status; + return EFI_SUCCESS; } static efi_status_t qsee_uefi_set_variable(struct qcuefi_client *qcuefi, const efi_char16_t *name, const efi_guid_t *guid, u32 attributes, unsigned long data_size, const void *data) { - struct qsee_req_uefi_set_variable *req_data; - struct qsee_rsp_uefi_set_variable *rsp_data; - efi_status_t efi_status = EFI_SUCCESS; + struct qsee_req_uefi_set_variable *req_data __free(kfree) = NULL; + struct qsee_rsp_uefi_set_variable *rsp_data __free(kfree) = NULL; unsigned long name_length; size_t name_offs; size_t guid_offs; @@ -451,16 +426,12 @@ static efi_status_t qsee_uefi_set_variable(struct qcuefi_client *qcuefi, const e ); req_data = kzalloc(req_size, GFP_KERNEL); - if (!req_data) { - efi_status = EFI_OUT_OF_RESOURCES; - goto out; - } + if (!req_data) + return EFI_OUT_OF_RESOURCES; rsp_data = kzalloc(sizeof(*rsp_data), GFP_KERNEL); - if (!rsp_data) { - efi_status = EFI_OUT_OF_RESOURCES; - goto out_free_req; - } + if (!rsp_data) + return EFI_OUT_OF_RESOURCES; req_data->command_id = QSEE_CMD_UEFI_SET_VARIABLE; req_data->attributes = attributes; @@ -473,10 +444,8 @@ static efi_status_t qsee_uefi_set_variable(struct qcuefi_client *qcuefi, const e req_data->length = req_size; status = ucs2_strscpy(((void *)req_data) + req_data->name_offset, name, name_length); - if (status < 0) { - efi_status = EFI_INVALID_PARAMETER; - goto out_free; - } + if (status < 0) + return EFI_INVALID_PARAMETER; memcpy(((void *)req_data) + req_data->guid_offset, guid, req_data->guid_size); @@ -485,42 +454,31 @@ static efi_status_t qsee_uefi_set_variable(struct qcuefi_client *qcuefi, const e status = qcom_qseecom_app_send(qcuefi->client, req_data, req_size, rsp_data, sizeof(*rsp_data)); - if (status) { - efi_status = EFI_DEVICE_ERROR; - goto out_free; - } + if (status) + return EFI_DEVICE_ERROR; - if (rsp_data->command_id != QSEE_CMD_UEFI_SET_VARIABLE) { - efi_status = EFI_DEVICE_ERROR; - goto out_free; - } + if (rsp_data->command_id != QSEE_CMD_UEFI_SET_VARIABLE) + return EFI_DEVICE_ERROR; - if (rsp_data->length != sizeof(*rsp_data)) { - efi_status = EFI_DEVICE_ERROR; - goto out_free; - } + if (rsp_data->length != sizeof(*rsp_data)) + return EFI_DEVICE_ERROR; if (rsp_data->status) { dev_dbg(qcuefi_dev(qcuefi), "%s: uefisecapp error: 0x%x\n", __func__, rsp_data->status); - efi_status = qsee_uefi_status_to_efi(rsp_data->status); + return qsee_uefi_status_to_efi(rsp_data->status); } -out_free: - kfree(rsp_data); -out_free_req: - kfree(req_data); -out: - return efi_status; + return EFI_SUCCESS; } static efi_status_t qsee_uefi_get_next_variable(struct qcuefi_client *qcuefi, unsigned long *name_size, efi_char16_t *name, efi_guid_t *guid) { - struct qsee_req_uefi_get_next_variable *req_data; - struct qsee_rsp_uefi_get_next_variable *rsp_data; - efi_status_t efi_status = EFI_SUCCESS; + struct qsee_req_uefi_get_next_variable *req_data __free(kfree) = NULL; + struct qsee_rsp_uefi_get_next_variable *rsp_data __free(kfree) = NULL; + efi_status_t efi_status; size_t guid_offs; size_t name_offs; size_t req_size; @@ -546,16 +504,12 @@ static efi_status_t qsee_uefi_get_next_variable(struct qcuefi_client *qcuefi, ); req_data = kzalloc(req_size, GFP_KERNEL); - if (!req_data) { - efi_status = EFI_OUT_OF_RESOURCES; - goto out; - } + if (!req_data) + return EFI_OUT_OF_RESOURCES; rsp_data = kzalloc(rsp_size, GFP_KERNEL); - if (!rsp_data) { - efi_status = EFI_OUT_OF_RESOURCES; - goto out_free_req; - } + if (!rsp_data) + return EFI_OUT_OF_RESOURCES; req_data->command_id = QSEE_CMD_UEFI_GET_NEXT_VARIABLE; req_data->guid_offset = guid_offs; @@ -567,26 +521,18 @@ static efi_status_t qsee_uefi_get_next_variable(struct qcuefi_client *qcuefi, memcpy(((void *)req_data) + req_data->guid_offset, guid, req_data->guid_size); status = ucs2_strscpy(((void *)req_data) + req_data->name_offset, name, *name_size / sizeof(*name)); - if (status < 0) { - efi_status = EFI_INVALID_PARAMETER; - goto out_free; - } + if (status < 0) + return EFI_INVALID_PARAMETER; status = qcom_qseecom_app_send(qcuefi->client, req_data, req_size, rsp_data, rsp_size); - if (status) { - efi_status = EFI_DEVICE_ERROR; - goto out_free; - } + if (status) + return EFI_DEVICE_ERROR; - if (rsp_data->command_id != QSEE_CMD_UEFI_GET_NEXT_VARIABLE) { - efi_status = EFI_DEVICE_ERROR; - goto out_free; - } + if (rsp_data->command_id != QSEE_CMD_UEFI_GET_NEXT_VARIABLE) + return EFI_DEVICE_ERROR; - if (rsp_data->length < sizeof(*rsp_data)) { - efi_status = EFI_DEVICE_ERROR; - goto out_free; - } + if (rsp_data->length < sizeof(*rsp_data)) + return EFI_DEVICE_ERROR; if (rsp_data->status) { dev_dbg(qcuefi_dev(qcuefi), "%s: uefisecapp error: 0x%x\n", @@ -601,77 +547,57 @@ static efi_status_t qsee_uefi_get_next_variable(struct qcuefi_client *qcuefi, if (efi_status == EFI_BUFFER_TOO_SMALL) *name_size = rsp_data->name_size; - goto out_free; + return efi_status; } - if (rsp_data->length > rsp_size) { - efi_status = EFI_DEVICE_ERROR; - goto out_free; - } + if (rsp_data->length > rsp_size) + return EFI_DEVICE_ERROR; - if (rsp_data->name_offset + rsp_data->name_size > rsp_data->length) { - efi_status = EFI_DEVICE_ERROR; - goto out_free; - } + if (rsp_data->name_offset + rsp_data->name_size > rsp_data->length) + return EFI_DEVICE_ERROR; - if (rsp_data->guid_offset + rsp_data->guid_size > rsp_data->length) { - efi_status = EFI_DEVICE_ERROR; - goto out_free; - } + if (rsp_data->guid_offset + rsp_data->guid_size > rsp_data->length) + return EFI_DEVICE_ERROR; if (rsp_data->name_size > *name_size) { *name_size = rsp_data->name_size; - efi_status = EFI_BUFFER_TOO_SMALL; - goto out_free; + return EFI_BUFFER_TOO_SMALL; } - if (rsp_data->guid_size != sizeof(*guid)) { - efi_status = EFI_DEVICE_ERROR; - goto out_free; - } + if (rsp_data->guid_size != sizeof(*guid)) + return EFI_DEVICE_ERROR; memcpy(guid, ((void *)rsp_data) + rsp_data->guid_offset, rsp_data->guid_size); status = ucs2_strscpy(name, ((void *)rsp_data) + rsp_data->name_offset, rsp_data->name_size / sizeof(*name)); *name_size = rsp_data->name_size; - if (status < 0) { + if (status < 0) /* * Return EFI_DEVICE_ERROR here because the buffer size should * have already been validated above, causing this function to * bail with EFI_BUFFER_TOO_SMALL. */ - efi_status = EFI_DEVICE_ERROR; - } + return EFI_DEVICE_ERROR; -out_free: - kfree(rsp_data); -out_free_req: - kfree(req_data); -out: - return efi_status; + return EFI_SUCCESS; } static efi_status_t qsee_uefi_query_variable_info(struct qcuefi_client *qcuefi, u32 attr, u64 *storage_space, u64 *remaining_space, u64 *max_variable_size) { - struct qsee_req_uefi_query_variable_info *req_data; - struct qsee_rsp_uefi_query_variable_info *rsp_data; - efi_status_t efi_status = EFI_SUCCESS; + struct qsee_req_uefi_query_variable_info *req_data __free(kfree) = NULL; + struct qsee_rsp_uefi_query_variable_info *rsp_data __free(kfree) = NULL; int status; req_data = kzalloc(sizeof(*req_data), GFP_KERNEL); - if (!req_data) { - efi_status = EFI_OUT_OF_RESOURCES; - goto out; - } + if (!req_data) + return EFI_OUT_OF_RESOURCES; rsp_data = kzalloc(sizeof(*rsp_data), GFP_KERNEL); - if (!rsp_data) { - efi_status = EFI_OUT_OF_RESOURCES; - goto out_free_req; - } + if (!rsp_data) + return EFI_OUT_OF_RESOURCES; req_data->command_id = QSEE_CMD_UEFI_QUERY_VARIABLE_INFO; req_data->attributes = attr; @@ -679,26 +605,19 @@ static efi_status_t qsee_uefi_query_variable_info(struct qcuefi_client *qcuefi, status = qcom_qseecom_app_send(qcuefi->client, req_data, sizeof(*req_data), rsp_data, sizeof(*rsp_data)); - if (status) { - efi_status = EFI_DEVICE_ERROR; - goto out_free; - } + if (status) + return EFI_DEVICE_ERROR; - if (rsp_data->command_id != QSEE_CMD_UEFI_QUERY_VARIABLE_INFO) { - efi_status = EFI_DEVICE_ERROR; - goto out_free; - } + if (rsp_data->command_id != QSEE_CMD_UEFI_QUERY_VARIABLE_INFO) + return EFI_DEVICE_ERROR; - if (rsp_data->length != sizeof(*rsp_data)) { - efi_status = EFI_DEVICE_ERROR; - goto out_free; - } + if (rsp_data->length != sizeof(*rsp_data)) + return EFI_DEVICE_ERROR; if (rsp_data->status) { dev_dbg(qcuefi_dev(qcuefi), "%s: uefisecapp error: 0x%x\n", __func__, rsp_data->status); - efi_status = qsee_uefi_status_to_efi(rsp_data->status); - goto out_free; + return qsee_uefi_status_to_efi(rsp_data->status); } if (storage_space) @@ -710,12 +629,7 @@ static efi_status_t qsee_uefi_query_variable_info(struct qcuefi_client *qcuefi, if (max_variable_size) *max_variable_size = rsp_data->max_variable_size; -out_free: - kfree(rsp_data); -out_free_req: - kfree(req_data); -out: - return efi_status; + return EFI_SUCCESS; } /* -- Global efivar interface. ---------------------------------------------- */