From patchwork Mon Jan 1 17:31:24 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Aishwarya Pant X-Patchwork-Id: 854336 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=none (mailfrom) smtp.mailfrom=vger.kernel.org (client-ip=209.132.180.67; helo=vger.kernel.org; envelope-from=linux-rtc-owner@vger.kernel.org; receiver=) Authentication-Results: ozlabs.org; dkim=pass (2048-bit key; unprotected) header.d=gmail.com header.i=@gmail.com header.b="eucjyVKL"; dkim-atps=neutral Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by ozlabs.org (Postfix) with ESMTP id 3z9PPs58b6z9s7s for ; Tue, 2 Jan 2018 04:31:45 +1100 (AEDT) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1751940AbeAARbd (ORCPT ); Mon, 1 Jan 2018 12:31:33 -0500 Received: from mail-pg0-f66.google.com ([74.125.83.66]:35073 "EHLO mail-pg0-f66.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1751888AbeAARbb (ORCPT ); Mon, 1 Jan 2018 12:31:31 -0500 Received: by mail-pg0-f66.google.com with SMTP id b70so167368pga.2; Mon, 01 Jan 2018 09:31:31 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=date:from:to:cc:subject:message-id:references:mime-version :content-disposition:in-reply-to:user-agent; bh=HhlUJfW304kQhN4oN188njBvQaiv6jHycZGdmUfGRs0=; b=eucjyVKLph6weA6Q3UUY8PpGzBsgwTgFT9Yl5GISuCSuNxW1y4+wBMwMzLsf9CXuN1 gJrcpeT6IV8PvqCqwGY/2GzchDefApM7QqCcRpDyuxSLu1qBoRPloItaf9SNGyuSc85k qRrdLurmXXxfTB08Kc+XwfaUVTEuHaeFSFVZl/4R8r9Fgj/IzOhI7NthycHoPwWZTM4b 5bXE4aBWDsjVDyVnjXqiQs9cFaw7TaGG/h7fIosgIy3k6D8RvvkukhZTd3z+ytNpRagT T6IVXuxx/vr3yZgFaZGJ3+svFJAuA63wc+FBVYivaBZgIzVYVnH3Ue0us0+cShvxfcHq NDHw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:date:from:to:cc:subject:message-id:references :mime-version:content-disposition:in-reply-to:user-agent; bh=HhlUJfW304kQhN4oN188njBvQaiv6jHycZGdmUfGRs0=; b=NaAyMMYpDgKTNemknpbBh4dgClMWSpdFgZiFL62dmVjpE0xR3vwhB4bzYygZbtv/ZG T90iAj5QeQdqiZ5qtx8NfxxkaZH0Z8NE2tBaVmyLx0tIwtZHr0UmiVxrsAkfXAHqvQlO VY5u0xFj5FEf2HBM7I6Fq9oPlPS5q2sV2HoNZ0p/E5/uvP/4oDrV1tWvWEvNNQeE6Z/K omM6oHU4w4ym9ia2QU9xTeZppooDwNvWeNsbheNxQt09xv8xj/j1Rdz/OXdR7Xlj5Sm1 Wxh/RtaZ9uFSM1CHsocAj9m84y49sQ5QeZxZv+4TbPlLVpuZsUwfCWiOs1Ku8q85dytZ NUJw== X-Gm-Message-State: AKGB3mKZsNqHjRxX9VvENymFHnktcUyhxlNwBKXLFaYaopTQIppRHphG FLtQhJrXVTtAQz9ESYf3nlU= X-Google-Smtp-Source: ACJfBosYNtnemGQTkplcmKpBTwFS2Nls1EnbVRqVkoXD4YzqXgFAr17VAv8+V35rBNOEMw+ythy2Gg== X-Received: by 10.98.138.149 with SMTP id o21mr43425264pfk.225.1514827890632; Mon, 01 Jan 2018 09:31:30 -0800 (PST) Received: from mordor.localdomain ([183.82.21.239]) by smtp.gmail.com with ESMTPSA id g9sm32090394pgr.4.2018.01.01.09.31.27 (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Mon, 01 Jan 2018 09:31:30 -0800 (PST) Date: Mon, 1 Jan 2018 23:01:24 +0530 From: Aishwarya Pant To: Alessandro Zummo , Alexandre Belloni , Jonathan Corbet , linux-rtc@vger.kernel.org, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, linux-api@vger.kernel.org Cc: Julia Lawall , gregkh@linuxfoundation.org Subject: [PATCH 2/2] Documentation: rtc: move iotcl interface documentation to ABI Message-ID: References: MIME-Version: 1.0 Content-Disposition: inline In-Reply-To: User-Agent: Mutt/1.9.2 (2017-12-15) Sender: linux-rtc-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-rtc@vger.kernel.org The ioctl interface should be in Documentation/ABI along with the rest of the interfaces. Signed-off-by: Aishwarya Pant --- Documentation/ABI/testing/rtc-cdev | 42 ++++++++++++++++++++++++++++++++ Documentation/rtc.txt | 49 ++------------------------------------ 2 files changed, 44 insertions(+), 47 deletions(-) create mode 100644 Documentation/ABI/testing/rtc-cdev diff --git a/Documentation/ABI/testing/rtc-cdev b/Documentation/ABI/testing/rtc-cdev new file mode 100644 index 000000000000..97447283f13b --- /dev/null +++ b/Documentation/ABI/testing/rtc-cdev @@ -0,0 +1,42 @@ +What: /dev/rtcX +Date: April 2005 +KernelVersion: 2.6.12 +Contact: linux-rtc@vger.kernel.org +Description: + The ioctl interface to drivers for real-time clocks (RTCs). + Following actions are supported: + + * RTC_RD_TIME, RTC_SET_TIME: Read or set the RTC time. Time + format is a Gregorian calendar date and 24 hour wall clock + time. + + * RTC_AIE_ON, RTC_AIE_OFF: Enable or disable the alarm interrupt + for RTCs that support alarms + + * RTC_ALM_READ, RTC_ALM_SET: Read or set the alarm time for + RTCs that support alarms. Can be set upto 24 hours in the + future. Requires a separate RTC_AIE_ON call to enable the + alarm interrupt. (Prefer to use RTC_WKALM_*) + + * RTC_WKALM_RD, RTC_WKALM_SET: For RTCs that support a more + powerful interface, which can issue alarms beyond 24 hours and + enable IRQs in the same request. + + * RTC_PIE_ON, RTC_PIE_OFF: Enable or disable the periodic + interrupt for RTCs that support periodic interrupts. + + * RTC_UIE_ON, RTC_UIE_OFF: Enable or disable the update + interrupt for RTCs that support it. + + * RTC_IRQP_READ, RTC_IRQP_SET: Read or set the frequency for + periodic interrupts for RTCs that support periodic interrupts. + Requires a separate RTC_PIE_ON call to enable the periodic + interrupts. + + The ioctl() calls supported by the older /dev/rtc interface are + also supported by the newer RTC class framework. However, + because the chips and systems are not standardized, some PC/AT + functionality might not be provided. And in the same way, some + newer features -- including those enabled by ACPI -- are exposed + by the RTC class framework, but can't be supported by the older + driver. diff --git a/Documentation/rtc.txt b/Documentation/rtc.txt index f521262cdc85..a129acf38537 100644 --- a/Documentation/rtc.txt +++ b/Documentation/rtc.txt @@ -136,50 +136,5 @@ a high functionality RTC is integrated into the SOC. That system might read the system clock from the discrete RTC, but use the integrated one for all other tasks, because of its greater functionality. -IOCTL interface ---------------- - -The ioctl() calls supported by /dev/rtc are also supported by the RTC class -framework. However, because the chips and systems are not standardized, -some PC/AT functionality might not be provided. And in the same way, some -newer features -- including those enabled by ACPI -- are exposed by the -RTC class framework, but can't be supported by the older driver. - - * RTC_RD_TIME, RTC_SET_TIME ... every RTC supports at least reading - time, returning the result as a Gregorian calendar date and 24 hour - wall clock time. To be most useful, this time may also be updated. - - * RTC_AIE_ON, RTC_AIE_OFF, RTC_ALM_SET, RTC_ALM_READ ... when the RTC - is connected to an IRQ line, it can often issue an alarm IRQ up to - 24 hours in the future. (Use RTC_WKALM_* by preference.) - - * RTC_WKALM_SET, RTC_WKALM_RD ... RTCs that can issue alarms beyond - the next 24 hours use a slightly more powerful API, which supports - setting the longer alarm time and enabling its IRQ using a single - request (using the same model as EFI firmware). - - * RTC_UIE_ON, RTC_UIE_OFF ... if the RTC offers IRQs, the RTC framework - will emulate this mechanism. - - * RTC_PIE_ON, RTC_PIE_OFF, RTC_IRQP_SET, RTC_IRQP_READ ... these icotls - are emulated via a kernel hrtimer. - -In many cases, the RTC alarm can be a system wake event, used to force -Linux out of a low power sleep state (or hibernation) back to a fully -operational state. For example, a system could enter a deep power saving -state until it's time to execute some scheduled tasks. - -Note that many of these ioctls are handled by the common rtc-dev interface. -Some common examples: - - * RTC_RD_TIME, RTC_SET_TIME: the read_time/set_time functions will be - called with appropriate values. - - * RTC_ALM_SET, RTC_ALM_READ, RTC_WKALM_SET, RTC_WKALM_RD: gets or sets - the alarm rtc_timer. May call the set_alarm driver function. - - * RTC_IRQP_SET, RTC_IRQP_READ: These are emulated by the generic code. - - * RTC_PIE_ON, RTC_PIE_OFF: These are also emulated by the generic code. - -If all else fails, check out the tools/testing/selftests/timers/rtctest.c test! +Check out tools/testing/selftests/timers/rtctest.c for an example usage of the +ioctl interface.