[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: [RFC PATCH v3 2/4] virtio-rtc: Add initial normative statements
Add the normative statements for the initial device specification. Signed-off-by: Peter Hilber <peter.hilber@opensynergy.com> --- conformance.tex | 2 + device-types/rtc/description.tex | 207 ++++++++++++++++++++++++ device-types/rtc/device-conformance.tex | 9 ++ device-types/rtc/driver-conformance.tex | 9 ++ 4 files changed, 227 insertions(+) create mode 100644 device-types/rtc/device-conformance.tex create mode 100644 device-types/rtc/driver-conformance.tex diff --git a/conformance.tex b/conformance.tex index 863f9c5825bf..c9a8137f50bf 100644 --- a/conformance.tex +++ b/conformance.tex @@ -153,6 +153,7 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets} \input{device-types/scmi/driver-conformance.tex} \input{device-types/gpio/driver-conformance.tex} \input{device-types/pmem/driver-conformance.tex} +\input{device-types/rtc/driver-conformance.tex} \conformance{\section}{Device Conformance}\label{sec:Conformance / Device Conformance} @@ -240,6 +241,7 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets} \input{device-types/scmi/device-conformance.tex} \input{device-types/gpio/device-conformance.tex} \input{device-types/pmem/device-conformance.tex} +\input{device-types/rtc/device-conformance.tex} \conformance{\section}{Legacy Interface: Transitional Device and Transitional Driver Conformance}\label{sec:Conformance / Legacy Interface: Transitional Device and Transitional Driver Conformance} A conformant implementation MUST be either transitional or diff --git a/device-types/rtc/description.tex b/device-types/rtc/description.tex index abfa2206894e..7707472f1663 100644 --- a/device-types/rtc/description.tex +++ b/device-types/rtc/description.tex @@ -98,6 +98,108 @@ \subsection{Device Operation}\label{sec:Device Types / RTC Device / Device Opera zero-based, dense indices. All fields named \field{clock_id} contain clock identifiers. +\drivernormative{\subsubsection}{Device Operation}{Device Types / RTC Device / Device Operation} + +If the \field{struct virtio_rtc_resp_head} field \field{status} is not +VIRTIO_RTC_S_OK, the driver MUST NOT interpret response fields other +than \field{status}. + +The driver MUST set \emph{reserved} fields in the device-readable part +of the message to zero. + +The driver MUST NOT interpret \emph{reserved} fields in the +device-writable part of the message. + +The driver MUST NOT interpret unnamed bits in \emph{flags} fields in the +device-writable part of the message. + +The driver MUST put the request into the device-readable part of the +message. + +The driver MUST allocate enough space for the response in the +device-writable part of a requestq message. + +\devicenormative{\subsubsection}{Device Operation}{Device Types / RTC Device / Device Operation} + +For \field{struct virtio_rtc_resp_head}, the device MUST set the +\field{status} field to VIRTIO_RTC_S_OK if the device successfully +executed the request. + +For \field{struct virtio_rtc_resp_head}, the device MUST set the +\field{status} field to a status other than VIRTIO_RTC_S_OK if the +device did not successfully execute the request. + +For \field{struct virtio_rtc_resp_head}, the device MUST set the +\field{status} field to VIRTIO_RTC_S_EOPNOTSUPP if the device could not +execute the specific request due to an implementation limitation. + +For \field{struct virtio_rtc_resp_head}, the device MUST set the +\field{status} field to VIRTIO_RTC_S_EOPNOTSUPP for a request with a +value of the \field{msg_type} field which is not described in this +specification. + +For \field{struct virtio_rtc_resp_head}, the device MUST set the +\field{status} field to VIRTIO_RTC_S_EOPNOTSUPP for a request with a +value of the \field{hw_counter} field which is neither described in this +specification nor otherwise known to the implementation. + +For \field{struct virtio_rtc_resp_head}, the device MUST set the +\field{status} field to VIRTIO_RTC_S_ENODEV if the \field{clock_id} +field value supplied with the request does not identify a clock. + +For \field{struct virtio_rtc_resp_head}, the device MUST set the +\field{status} field to VIRTIO_RTC_S_EINVAL if the request values are +inconsistent with the specification and if the inconsistence is not +described by the requirements which stipulate status +VIRTIO_RTC_S_EOPNOTSUPP or VIRTIO_RTC_S_ENODEV. + +For \field{struct virtio_rtc_resp_head}, the device MUST set the +\field{status} field to VIRTIO_RTC_S_EINVAL if the device read-only part +of the message is too small. + +For \field{struct virtio_rtc_resp_head}, the device MUST set the +\field{status} field to VIRTIO_RTC_S_EINVAL if the device write-only +part of the message is too small, unless the \field{status} field does +not fit into the device write-only part. + +For \field{struct virtio_rtc_resp_head}, the device MUST NOT set the +\field{status} field if the \field{status} field does not fit into the +device write-only part. + +For \field{struct virtio_rtc_resp_head}, the device MUST set the +\field{status} field to VIRTIO_RTC_S_EIO if none of the previous +requirements in this document stipulated another \field{status}. + +If the device read-only part of a message M is bigger than the size of +the request specified for message M, the device MUST ignore the +additional space. + +If the device write-only part of a message M is bigger than the size of +the response specified for message M, the device MUST ignore the +additional space. + +The device MUST NOT interpret \emph{reserved} fields in the +device-readable part of the message. + +The device MUST set \emph{reserved} fields in the device-writable part +of the message to zero. + +The device MUST set unnamed bits in \emph{flags} fields in the +device-writable part of the message to zero. + +After feature negotiation completion the device MUST NOT change the set +of clocks until device reset. + +The device SHOULD NOT change the set of clocks on a device reset after +the first device reset. + +The device MUST use non-negative integers, which are smaller than the +number of clocks, as clock identifiers. + +For a fixed request value V, the device SHOULD either, for every request +with value V, always execute successfully, or, for every request with +value V, always set a fixed \field{status} other than VIRTIO_RTC_S_OK. + \subsubsection{Control Requests}\label{sec:Device Types / RTC Device / Device Operation / Control Requests} Through \emph{control requests}, the driver requests information about @@ -203,6 +305,42 @@ \subsubsection{Control Requests}\label{sec:Device Types / RTC Device / Device Op \end{description} +\drivernormative{\paragraph}{Control Requests}{Device Types / RTC Device / Device Operation / Control Requests} + +For VIRTIO_RTC_REQ_CROSS_CAP, the driver MUST set \field{hw_counter} to +one of the hardware counter identifiers defined in this specification, +or to a value greater than or equal to 0xF000. + +\devicenormative{\paragraph}{Control Requests}{Device Types / RTC Device / Device Operation / Control Requests} + +For any clock of type VIRTIO_RTC_CLOCK_UTC, the device MUST use the UTC +time standard (Coordinated Universal Time). + +For any clock of type VIRTIO_RTC_CLOCK_UTC, the device MUST use the time +epoch of January 1, 1970, 00:00 UTC. + +For any clock of type VIRTIO_RTC_CLOCK_TAI, the device MUST use the TAI +time standard (International Atomic Time). + +For any clock of type VIRTIO_RTC_CLOCK_TAI, the device MUST use the time +epoch of January 1, 1970, 00:00 TAI. + +For any clock of type VIRTIO_RTC_CLOCK_MONO, the device MUST use SI +seconds subdivisions. + +For any clock of type VIRTIO_RTC_CLOCK_MONO, the device MUST use an +epoch at a time instant before or during device reset. + +For VIRTIO_RTC_REQ_CLOCK_CAP, the device MUST set \field{type} to +one of the clock types defined in this specification, or to a value +greater than or equal to 0xF000. + +For a VIRTIO_RTC_REQ_CROSS_CAP message M, the device MUST set the +VIRTIO_RTC_FLAG_CROSS_CAP flag in the \field{flags} field if the device +would respond to a VIRTIO_RTC_REQ_READ_CROSS message with the same +\field{hw_counter} and \field{clock_id} values as in M with status +VIRTIO_RTC_S_OK, and clear the flag otherwise. + \subsubsection{Read Requests}\label{sec:Device Types / RTC Device / Device Operation / Read Requests} Through \emph{read requests}, the driver requests clock readings from @@ -326,3 +464,72 @@ \subsubsection{Read Requests}\label{sec:Device Types / RTC Device / Device Opera through VIRTIO_RTC_REQ_CROSS_CAP. \end{description} + +\drivernormative{\paragraph}{Read Requests}{Device Types / RTC Device / Device Operation / Read Requests} + +For VIRTIO_RTC_REQ_READ_CROSS, the driver MUST set \field{hw_counter} to +one of the hardware counter identifiers defined in this specification, +or to a value greater than or equal to 0xF000. + +\devicenormative{\paragraph}{Read Requests}{Device Types / RTC Device / Device Operation / Read Requests} + +The device SHOULD continuously support reading of all clocks once +DRIVER_OK has been set. + +For any clock of type VIRTIO_RTC_CLOCK_UTC, the device MAY insert UTC +leap seconds. + +For any clock of type VIRTIO_RTC_CLOCK_UTC, the device MAY smear UTC +leap seconds through clock slewing. + +For any clock C and read requests \emph{A} and \emph{B} which read C, +\emph{A} being the message which the driver marks as available before +\emph{B}, the device MUST obtain the \field{clock_reading} value for the +message \emph{A} response before the \field{clock_reading} value for the +message \emph{B} response, or the device MUST obtain the same +\field{clock_reading} value for both \emph{A} and \emph{B}. + +For any clock C, the device MUST mark all read requests reading C as +used in the total order in which the driver marked these messages as +available. + +For any clock C of type VIRTIO_RTC_CLOCK_MONO and read requests +\emph{A} and \emph{B} which read C, \emph{A} being the message which the +driver marks as available before \emph{B}, the device MUST set the +\field{clock_reading} value for the message \emph{B} response to a value +greater than or equal to the \field{clock_reading} value for the message +\emph{A} response. + +The device MUST support VIRTIO_RTC_REQ_READ for every clock. + +For VIRTIO_RTC_REQ_READ and for any clock type listed in this +specification, the device MUST use the nanosecond as unit for field +\field{clock_reading}. + +For read requests, the device MUST obtain the \field{clock_reading} +response value after the read request is marked as available. + +For VIRTIO_RTC_REQ_READ_CROSS, the device MUST set +\field{counter_cycles} to a value which approximates the value which the +driver would have read from the hardware counter identified by +\field{hw_counter} at the time instant when the device read the +\field{clock_reading} value. + +For VIRTIO_RTC_REQ_READ_CROSS, the device MUST set \field{status} +to a value other than \field{VIRTIO_RTC_S_OK} if the device cannot +determine the approximate value which the driver would have read from +the hardware counter identified by \field{hw_counter} at the time +instant when the device read the \field{clock_reading} value. + +For any clock C, and VIRTIO_RTC_REQ_READ_CROSS messages \emph{A} and +\emph{B} which read C and which specify the same hardware counter +\emph{H} through field \field{hw_counter}, \emph{A} being the message +which the driver marks as available before \emph{B}, the device MUST set +the \field{counter_cycles} value for \emph{B} to a value which \emph{H} +shows after the \field{counter_cycles} value of \emph{A}, or the device +MUST set the same \field{counter_cycles} value for \emph{A} and +\emph{B}. + +For VIRTIO_RTC_REQ_READ_CROSS and for any clock type listed in +this specification, the device MUST use the nanosecond as unit for +field \field{clock_reading}. diff --git a/device-types/rtc/device-conformance.tex b/device-types/rtc/device-conformance.tex new file mode 100644 index 000000000000..4303cd450542 --- /dev/null +++ b/device-types/rtc/device-conformance.tex @@ -0,0 +1,9 @@ +\conformance{\subsection}{RTC Device Conformance}\label{sec:Conformance / Device Conformance / RTC Device Conformance} + +An RTC device MUST conform to the following normative statements: + +\begin{itemize} +\item \ref{devicenormative:Device Types / RTC Device / Device Operation} +\item \ref{devicenormative:Device Types / RTC Device / Device Operation / Control Requests} +\item \ref{devicenormative:Device Types / RTC Device / Device Operation / Read Requests} +\end{itemize} diff --git a/device-types/rtc/driver-conformance.tex b/device-types/rtc/driver-conformance.tex new file mode 100644 index 000000000000..689c18d158d0 --- /dev/null +++ b/device-types/rtc/driver-conformance.tex @@ -0,0 +1,9 @@ +\conformance{\subsection}{RTC Driver Conformance}\label{sec:Conformance / Driver Conformance / RTC Driver Conformance} + +An RTC driver MUST conform to the following normative statements: + +\begin{itemize} +\item \ref{drivernormative:Device Types / RTC Device / Device Operation} +\item \ref{drivernormative:Device Types / RTC Device / Device Operation / Control Requests} +\item \ref{drivernormative:Device Types / RTC Device / Device Operation / Read Requests} +\end{itemize} -- 2.40.1
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]