From patchwork Wed Apr 26 08:03:09 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: "D. Starke" X-Patchwork-Id: 87706 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:a59:b0ea:0:b0:3b6:4342:cba0 with SMTP id b10csp78131vqo; Wed, 26 Apr 2023 01:06:28 -0700 (PDT) X-Google-Smtp-Source: AKy350Z1iZ0wdwwvSRF2w2FxIT4nDe1wPrBVb2oSTpOGvmou7drWAO4BArF0TrK77pPWKbhqM8E4 X-Received: by 2002:a05:6a00:13aa:b0:637:f447:9916 with SMTP id t42-20020a056a0013aa00b00637f4479916mr28808278pfg.16.1682496388216; Wed, 26 Apr 2023 01:06:28 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1682496388; cv=none; d=google.com; s=arc-20160816; b=VO+Bv12npHwfFlG2yLrVkLx2MhS7kCiFUQZEzuUD//5c9J36zhMjTb7QEAhKe0g4oH tGxB1/G0vs5hqWMA6yjfps99qm46w47OhjQCS/LgSLBoaLEaye5yxxS4GY75Nl3TapQ4 uYG2IChKty5ddQufykKfmVToQhM1qTE0O8oTpkkjnTs1EvQ7Fn48k7dwDTFP8V8enpjD wltBVC6f1sPxljQvUUiWxgvPlCBg+U646Rsr98qsrkPwJHFJv4Lj5S49f395g/BpznAz y3OJNOxBZ4W6GogbtrVXfXOKzeHkseiYPuoLY3DbGI7LrsIM1kMQNhcSfEmqRx+GGcJx AHHg== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:feedback-id:content-transfer-encoding :mime-version:references:in-reply-to:message-id:date:subject:cc:to :from:dkim-signature; bh=yEGcgQ5Kvtx1tgonDU+9HHY5hBo4q5pCkYVLeZOHs5M=; b=TT2vso7d5wNgjTZflTt6jXTV+2ZAcUmM4EVaMKcHfq0zu9bh+t+9XErOXHclMuSRl6 2JB1i5OhDzYrLbeoi2mVzetaiJuBVWC6++gMZ/QpkGx/onwpcarJm+aIIJ7I64Qj7YmA A2AlAY9zZCUGCisRPme1ad9mJpMQzZ2/+hbCbnqL/ZMYabBbXpntPvdPZWzGiTflun2N 5qQZtPngaPx5ubqsH7LBR1IoBnY8s8KASii0ZFowlwKMOJIjrpZWpJqJK16GyZ+WPXaz XGEw3S4Cgv110LFgc3ci6pMF6P2haxaQiyc6yxk4aSFeZWrnMtKcfuTTu2Ll09N7j58x u7SQ== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@siemens.com header.s=fm1 header.b=pPtLUQAU; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=REJECT sp=REJECT dis=NONE) header.from=siemens.com Received: from out1.vger.email (out1.vger.email. [2620:137:e000::1:20]) by mx.google.com with ESMTP id v20-20020a634654000000b005139e0d2b5csi10763006pgk.487.2023.04.26.01.06.11; Wed, 26 Apr 2023 01:06:28 -0700 (PDT) Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20; Authentication-Results: mx.google.com; dkim=pass header.i=@siemens.com header.s=fm1 header.b=pPtLUQAU; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=REJECT sp=REJECT dis=NONE) header.from=siemens.com Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S239988AbjDZIDn (ORCPT + 99 others); Wed, 26 Apr 2023 04:03:43 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:57640 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S239640AbjDZIDg (ORCPT ); Wed, 26 Apr 2023 04:03:36 -0400 Received: from mta-65-227.siemens.flowmailer.net (mta-65-227.siemens.flowmailer.net [185.136.65.227]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 12DEE3AAD for ; Wed, 26 Apr 2023 01:03:32 -0700 (PDT) Received: by mta-65-227.siemens.flowmailer.net with ESMTPSA id 20230426080330429f5db1f9e012e83b for ; Wed, 26 Apr 2023 10:03:30 +0200 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; s=fm1; d=siemens.com; i=daniel.starke@siemens.com; h=Date:From:Subject:To:Message-ID:MIME-Version:Content-Type:Content-Transfer-Encoding:Cc:References:In-Reply-To; bh=yEGcgQ5Kvtx1tgonDU+9HHY5hBo4q5pCkYVLeZOHs5M=; b=pPtLUQAUadLjVnVs6hB73r7wlCQNX66VtpS9hgOjmZx+bjh7yUSUhnk0wqiOJfmvmymY+G 2S+2knT+AGT5BWzXKSI8Gbcrl4ZSGDaFINdQnhtioG1csliGbRngHDJu8RYd7pjT6FrIDCEB YkC8PZxduG2jn/ql1GQBoTVWeHf90=; From: "D. Starke" To: linux-serial@vger.kernel.org, gregkh@linuxfoundation.org, jirislaby@kernel.org, ilpo.jarvinen@linux.intel.com Cc: linux-kernel@vger.kernel.org, Daniel Starke Subject: [PATCH v4 2/8] tty: n_gsm: add missing description to structs in gsmmux.h Date: Wed, 26 Apr 2023 10:03:09 +0200 Message-Id: <20230426080315.7595-2-daniel.starke@siemens.com> In-Reply-To: <20230426080315.7595-1-daniel.starke@siemens.com> References: <20230426080315.7595-1-daniel.starke@siemens.com> MIME-Version: 1.0 X-Flowmailer-Platform: Siemens Feedback-ID: 519:519-314044:519-21489:flowmailer X-Spam-Status: No, score=-2.1 required=5.0 tests=BAYES_00,DKIMWL_WL_MED, DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,RCVD_IN_MSPIKE_H2, SPF_HELO_PASS,SPF_PASS,T_SCC_BODY_TEXT_LINE,URIBL_BLOCKED autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on lindbergh.monkeyblade.net Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org X-getmail-retrieved-from-mailbox: =?utf-8?q?INBOX?= X-GMAIL-THRID: =?utf-8?q?1764225332787311916?= X-GMAIL-MSGID: =?utf-8?q?1764225332787311916?= From: Daniel Starke Currently, all available structure fields in gsmmux.h except those for gsm_config are commented. Furthermore, no kernel doc comments are used. Fix this by adding appropriate comments to the not commented fields of gsm_config. Convert the comments of the other structs to kernel doc format. Note that 'mru' and 'mtu' refer to the size without basic/advanced option mode header and byte stuffing as defined in the standard in chapter 5.7.2. Link: https://portal.3gpp.org/desktopmodules/Specifications/SpecificationDetails.aspx?specificationId=1516 Signed-off-by: Daniel Starke --- include/uapi/linux/gsmmux.h | 104 +++++++++++++++++++++++++++++------- 1 file changed, 84 insertions(+), 20 deletions(-) v3 -> v4: Changed comments of all other structs in gsmmux.h to kernel doc format as suggested during review. The patch description and subject was changed to match this. Link: https://lore.kernel.org/all/2023042438-whole-cannot-1945@gregkh/ Link: https://lore.kernel.org/all/20230424075251.5216-2-daniel.starke@siemens.com/ diff --git a/include/uapi/linux/gsmmux.h b/include/uapi/linux/gsmmux.h index 958257af05ab..54bc8767bd75 100644 --- a/include/uapi/linux/gsmmux.h +++ b/include/uapi/linux/gsmmux.h @@ -16,6 +16,28 @@ /* Force DLCI channel reset? Always cleared on retrieval. */ #define GSM_FL_RESTART _BITUL(0) +/** + * struct gsm_config - n_gsm basic configuration parameters + * + * This structure is used in combination with GSMIOC_GETCONF and GSMIOC_SETCONF + * to retrieve and set the basic parameters of an n_gsm ldisc. + * struct gsm_config_ext can be used to configure extended ldisc parameters. + * + * All timers are in units of 1/100th of a second. + * + * @adaption: Convergence layer type + * @encapsulation: Framing (0 = basic option, 1 = advanced option) + * @initiator: Initiator or responder + * @t1: Acknowledgment timer + * @t2: Response timer for multiplexer control channel + * @t3: Response timer for wake-up procedure + * @n2: Maximum number of retransmissions + * @mru: Maximum incoming frame payload size + * @mtu: Maximum outgoing frame payload size + * @k: Window size + * @i: Frame type (1 = UIH, 2 = UI) + * @unused: Can not be used + */ struct gsm_config { unsigned int adaption; @@ -29,18 +51,32 @@ struct gsm_config unsigned int mtu; unsigned int k; unsigned int i; - unsigned int unused[8]; /* Can not be used */ + unsigned int unused[8]; }; #define GSMIOC_GETCONF _IOR('G', 0, struct gsm_config) #define GSMIOC_SETCONF _IOW('G', 1, struct gsm_config) +/** + * struct gsm_netconfig - n_gsm network configuration parameters + * + * This structure is used in combination with GSMIOC_ENABLE_NET and + * GSMIOC_DISABLE_NET to enable or disable a network data connection + * over a mux virtual tty channel. This is for modems that support + * data connections with raw IP frames instead of PPP. + * + * @adaption: Adaption to use in network mode. + * @protocol: Protocol to use - only ETH_P_IP supported. + * @unused2: Can not be used. + * @if_name: Interface name format string. + * @unused: Can not be used. + */ struct gsm_netconfig { - unsigned int adaption; /* Adaption to use in network mode */ - unsigned short protocol;/* Protocol to use - only ETH_P_IP supported */ - unsigned short unused2; /* Can not be used */ - char if_name[IFNAMSIZ]; /* interface name format string */ - __u8 unused[28]; /* Can not be used */ + unsigned int adaption; + unsigned short protocol; + unsigned short unused2; + char if_name[IFNAMSIZ]; + __u8 unused[28]; }; #define GSMIOC_ENABLE_NET _IOW('G', 2, struct gsm_netconfig) @@ -49,27 +85,55 @@ struct gsm_netconfig { /* get the base tty number for a configured gsmmux tty */ #define GSMIOC_GETFIRST _IOR('G', 4, __u32) +/** + * struct gsm_config_ext - n_gsm extended configuration parameters + * + * This structure is used in combination with GSMIOC_GETCONF_EXT and + * GSMIOC_SETCONF_EXT to retrieve and set the extended parameters of an + * n_gsm ldisc. + * + * All timers are in units of 1/100th of a second. + * + * @keep_alive: Control channel keep-alive in 1/100th of a second (0 to disable). + * @wait_config: Wait for DLCI config before opening virtual link? + * @reserved: For future use, must be initialized to zero. + */ struct gsm_config_ext { - __u32 keep_alive; /* Control channel keep-alive in 1/100th of a - * second (0 to disable) - */ - __u32 wait_config; /* Wait for DLCI config before opening virtual link? */ - __u32 reserved[6]; /* For future use, must be initialized to zero */ + __u32 keep_alive; + __u32 wait_config; + __u32 reserved[6]; }; #define GSMIOC_GETCONF_EXT _IOR('G', 5, struct gsm_config_ext) #define GSMIOC_SETCONF_EXT _IOW('G', 6, struct gsm_config_ext) -/* Set channel accordingly before calling GSMIOC_GETCONF_DLCI. */ +/** + * struct gsm_dlci_config - n_gsm channel configuration parameters + * + * This structure is used in combination with GSMIOC_GETCONF_DLCI and + * GSMIOC_SETCONF_DLCI to retrieve and set the channel specific parameters + * of an n_gsm ldisc. + * + * Set the channel accordingly before calling GSMIOC_GETCONF_DLCI. + * + * @channel: DLCI (0 for the associated DLCI). + * @adaption: Convergence layer type. + * @mtu: Maximum transfer unit. + * @priority: Priority (0 for default value). + * @i: Frame type (1 = UIH, 2 = UI). + * @k: Window size (0 for default value). + * @flags: DLCI specific flags. + * @reserved: For future use, must be initialized to zero. + */ struct gsm_dlci_config { - __u32 channel; /* DLCI (0 for the associated DLCI) */ - __u32 adaption; /* Convergence layer type */ - __u32 mtu; /* Maximum transfer unit */ - __u32 priority; /* Priority (0 for default value) */ - __u32 i; /* Frame type (1 = UIH, 2 = UI) */ - __u32 k; /* Window size (0 for default value) */ - __u32 flags; /* DLCI specific flags. */ - __u32 reserved[7]; /* For future use, must be initialized to zero */ + __u32 channel; + __u32 adaption; + __u32 mtu; + __u32 priority; + __u32 i; + __u32 k; + __u32 flags; + __u32 reserved[7]; }; #define GSMIOC_GETCONF_DLCI _IOWR('G', 7, struct gsm_dlci_config)