; Copyright 2009 Castle Technology Ltd
;
; Licensed under the Apache License, Version 2.0 (the "License");
; you may not use this file except in compliance with the License.
; You may obtain a copy of the License at
;
;     http://www.apache.org/licenses/LICENSE-2.0
;
; Unless required by applicable law or agreed to in writing, software
; distributed under the License is distributed on an "AS IS" BASIS,
; WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
; See the License for the specific language governing permissions and
; limitations under the License.
;

; Public interface (ie interface to the kernel) of RTC HAL devices

        GET     hdr:HALDevice

OldOpt  SETA    {OPT}
        OPT     OptNoList+OptNoP1List

 [ :LNOT: :DEF: Included_Hdr_RTCDevice
                       GBLL Included_Hdr_RTCDevice
Included_Hdr_RTCDevice SETL {TRUE}

; Device for each RTC controller

                                ^       0
                                #       HALDeviceSize
HALDevice_RTCTimeFormat         #       1
HALDevice_RTCFormatFlags        #       1
                                #       2 ; Padding
HALDevice_RTCReadTime           #       4
HALDevice_RTCWriteTime          #       4
HALDevice_RTC_Size              *       :INDEX: @

; Supported time formats for communication with RISC OS
RTCTimeFormat_BCD               *       0

; BCD format details
RTCFormatFlags_BCD_1BasedDay     *      1 :SHL: 0 ; is DayOfMonth 0-based or 1-based?
RTCFormatFlags_BCD_1BasedMonth   *      1 :SHL: 1 ; is Month 0-based or 1-based?
RTCFormatFlags_BCD_NeedsYearHelp *      1 :SHL: 2 ; If this is set, RISC OS assumes only the RTC is unable to store the full two-byte year.
RTCFormatFlags_BCD_YearLOIsGood  *      1 :SHL: 3 ; If this bit is not set, RISC OS treats YearLO as a 2-bit uint. Else it is treated as a 2-digit BCD value. If YearLOIsGood is not set, NeedsYearHelp must be set.

; Struct for storing BCD time
                                ^       0
RTCTimeStruct_BCD_Centiseconds  #       1
RTCTimeStruct_BCD_Seconds       #       1
RTCTimeStruct_BCD_Minutes       #       1
RTCTimeStruct_BCD_Hours         #       1
RTCTimeStruct_BCD_DayOfMonth    #       1
RTCTimeStruct_BCD_Month         #       1
RTCTimeStruct_BCD_YearLO        #       1 ; Note: Will be sent and received as a 2-bit int if YearLOIsGood is not set
RTCTimeStruct_BCD_YearHI        #       1
RTCTimeStruct_BCD_Size          *       :INDEX: @

; Return codes
RTCRetCode_OK                   *       0
RTCRetCode_Error                *       -1 ; Generic nonspecific error
RTCRetCode_InvalidTime          *       -2 ; For write operations, indicates that the RTC cannot be programmed with the supplied time. For read operations, indicates that the RTC has been detected as containing an invalid time (e.g. following power loss)

 ]

        OPT     OldOpt
        END