1$NetBSD: device_calls,v 1.4 2025/10/04 01:12:15 thorpej Exp $ 2 3/*- 4 * Copyright (c) 2021, 2025 The NetBSD Foundation, Inc. 5 * All rights reserved. 6 * 7 * This code is derived from software contributed to The NetBSD Foundation 8 * by Jason R. Thorpe. 9 * 10 * Redistribution and use in source and binary forms, with or without 11 * modification, are permitted provided that the following conditions 12 * are met: 13 * 1. Redistributions of source code must retain the above copyright 14 * notice, this list of conditions and the following disclaimer. 15 * 2. Redistributions in binary form must reproduce the above copyright 16 * notice, this list of conditions and the following disclaimer in the 17 * documentation and/or other materials provided with the distribution. 18 * 19 * THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 20 * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 21 * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 22 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 23 * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 24 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 25 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 26 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 27 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 28 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 29 * POSSIBILITY OF SUCH DAMAGE. 30 */ 31 32/* 33 * Device calls used by the device autoconfiguration subsystem 34 */ 35 36subsystem device; 37 38/* 39 * device-enumerate-children 40 * 41 * Enumerates the direct children of a device, invoking the callback for 42 * each one. The callback is passed the devhandle_t corresponding to the 43 * child device, as well as a user-supplied argument. If the callback 44 * returns true, then enumeration continues. If the callback returns false, 45 * enumeration is stopped. 46 */ 47device-enumerate-children { 48 bool (*callback)(device_t, devhandle_t, void *); 49 void * callback_arg; 50}; 51 52/* 53 * device-register 54 * 55 * This is a hook for the platform device tree implementation to 56 * inspect or take action upon a new device before the machine- 57 * specific device_register() function is called. 58 */ 59device-register { 60 void * aux; /* IN */ 61}; 62 63/* 64 * device-is-system-todr 65 * 66 * This is a filter that is considered when attaching the system TODR / RTC. 67 * For systems which may have multiple TODR / RTC devices, the platform 68 * device tree may have information about which is authoritative. This is 69 * an optional method, and in its absence, the system will proceed as if 70 * the answer was "yes". 71 */ 72device-is-system-todr { 73 bool result; /* OUT */ 74}; 75 76/* 77 * device-get-property 78 * 79 * Gets the specified property (and its attributes) and copies it into 80 * the caller-provided buffer, in addtion to returning the property's 81 * attributes: 82 * ==> propsize The native size of the property in the backing 83 * store. 84 * ==> encoding The native encoding of numbers in the backing store, 85 * _BIG_ENDIAN or _LITTLE_ENDIAN. 86 * ==> type The native type of the property in the backing store. 87 * If the backing store does not have a native typing 88 * system, then it may return PROP_TYPE_UNKNOWN for this 89 * attribute. 90 * 91 * If the requested property type is PROP_TYPE_UNKNOWN, then the pointer to 92 * and size of the caller-provided buffer shall be NULL and 0, respectively. 93 * Implementations may assert this. In this instance, the caller is requesting 94 * only the property's attributes. 95 * 96 * Conversely, if the requested property type is not PROP_TYPE_UNKNOWN, 97 * then the pointer to the caller-provided buffer shall not be NULL and 98 * the size shall not be 0, and the type will be one of the four listed 99 * below. Implementation may assert this. 100 * 101 * If the requested property type is PROP_TYPE_DATA or PROP_TYPE_STRING, 102 * then the following rules apply: 103 * ==> If the caller-provided buffer is insufficiently large to hold the 104 * entire property, the "propsize" output must be set to reflect the 105 * required buffer size and the EFBIG error returned. In this situation, 106 * it is unspecified whether or not any data is copied into the caller- 107 * provided buffer. 108 * ==> If the backing store has a native STRING type, then the implementation 109 * must allow STRING properties to be fetched as DATA objects. 110 * 111 * If the requested type is PROP_TYPE_STRING, the property value in returned 112 * in the caller-provided buffer must be NUL-terminated. 113 * 114 * If the requested property type is PROP_TYPE_NUMBER, then the following 115 * rules apply: 116 * ==> The size of the caller-provided buffer shall be sizeof(uint64_t) and 117 * will have alignment suitable for the type. Implementations may assert 118 * this. 119 * ==> The implementation must silently zero-extend whatever value is in the 120 * backing store to a uint64_t and return that value. The front-end 121 * will perform any type conversions, including range checks, requested 122 * by the caller. 123 * ==> The returned "propsize" must reflect an accurate representation of 124 * the size of the property in the backing store; this information is 125 * is used in type conversion. 126 * ==> If the backing store's number encoding differs from the native number 127 * encoding, then the backing store shall convert the number to the native 128 * encoding. 129 * 130 * If the requested property type is PROP_TYPE_BOOL, then the following 131 * rules apply: 132 * ==> The size of the caller-provided buffer shall be sizeof(bool) and will 133 * have alignment suitable for the type. Implementations may assert this. 134 * ==> If the implementation's backing store does not provide a native boolean 135 * type, then the implementation may use backing-store-specific conventions 136 * to infer bool-ness of the property. If, in this situation, the property 137 * does not match the backing store's boolean conventions, then the 138 * implementation must return EFTYPE; the system will then use its own 139 * default policy as a fallback. 140 * 141 * Call returns 0 if successful, or an error code upon failure: 142 * 143 * ENOENT The property does not exist. 144 * 145 * EFBIG The property is too large to fit in the provided buffer. 146 * The "propsize" output is set to reflect the required 147 * buffer size (for DATA and STRING properties). 148 * 149 * EFTYPE The property is a different type than what was requested. 150 * 151 * EINVAL The arguments provided to the call are invalid in a way 152 * not covered by one of the above error cases. 153 * 154 * EIO An input/output error to the backing store occurred. 155 * 156 * The "flags" field of the arguments structure is reserved for future 157 * expansion. 158 * 159 * The "dev" argument to the device-get-property call may be NULL. 160 */ 161device-get-property { 162 const char * prop; /* IN */ 163 void * buf; /* IN */ 164 size_t buflen; /* IN */ 165 prop_type_t reqtype; /* IN */ 166 int flags; /* IN */ 167 ssize_t propsize; /* OUT */ 168 int encoding; /* OUT */ 169 prop_type_t type; /* OUT */ 170}; 171