^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) /* SPDX-License-Identifier: GPL-2.0-only */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2) /*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3) * Linux WiMAX
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4) * Kernel space API for accessing WiMAX devices
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6) * Copyright (C) 2007-2008 Intel Corporation <linux-wimax@intel.com>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7) * Inaky Perez-Gonzalez <inaky.perez-gonzalez@intel.com>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9) * The WiMAX stack provides an API for controlling and managing the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10) * system's WiMAX devices. This API affects the control plane; the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) * data plane is accessed via the network stack (netdev).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) * Parts of the WiMAX stack API and notifications are exported to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) * user space via Generic Netlink. In user space, libwimax (part of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) * the wimax-tools package) provides a shim layer for accessing those
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) * calls.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) * The API is standarized for all WiMAX devices and different drivers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) * implement the backend support for it. However, device-specific
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) * messaging pipes are provided that can be used to issue commands and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) * receive notifications in free form.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) * Currently the messaging pipes are the only means of control as it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) * is not known (due to the lack of more devices in the market) what
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25) * will be a good abstraction layer. Expect this to change as more
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) * devices show in the market. This API is designed to be growable in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27) * order to address this problem.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) * USAGE
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) * Embed a `struct wimax_dev` at the beginning of the device's
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) * private structure, initialize and register it. For details, see
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33) * `struct wimax_dev`s documentation.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) * Once this is done, wimax-tools's libwimaxll can be used to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) * communicate with the driver from user space. You user space
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) * application does not have to forcibily use libwimaxll and can talk
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) * the generic netlink protocol directly if desired.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) * Remember this is a very low level API that will to provide all of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) * WiMAX features. Other daemons and services running in user space
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) * are the expected clients of it. They offer a higher level API that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43) * applications should use (an example of this is the Intel's WiMAX
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) * Network Service for the i2400m).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) * DESIGN
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) * Although not set on final stone, this very basic interface is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) * mostly completed. Remember this is meant to grow as new common
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) * operations are decided upon. New operations will be added to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) * interface, intent being on keeping backwards compatibility as much
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) * as possible.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) * This layer implements a set of calls to control a WiMAX device,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) * exposing a frontend to the rest of the kernel and user space (via
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) * generic netlink) and a backend implementation in the driver through
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57) * function pointers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59) * WiMAX devices have a state, and a kernel-only API allows the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) * drivers to manipulate that state. State transitions are atomic, and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) * only some of them are allowed (see `enum wimax_st`).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) * Most API calls will set the state automatically; in most cases
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) * drivers have to only report state changes due to external
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) * conditions.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67) * All API operations are 'atomic', serialized through a mutex in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) * `struct wimax_dev`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70) * EXPORTING TO USER SPACE THROUGH GENERIC NETLINK
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) * The API is exported to user space using generic netlink (other
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73) * methods can be added as needed).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75) * There is a Generic Netlink Family named "WiMAX", where interfaces
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) * supporting the WiMAX interface receive commands and broadcast their
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77) * signals over a multicast group named "msg".
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) * Mapping to the source/destination interface is done by an interface
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80) * index attribute.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) * For user-to-kernel traffic (commands) we use a function call
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83) * marshalling mechanism, where a message X with attributes A, B, C
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) * sent from user space to kernel space means executing the WiMAX API
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85) * call wimax_X(A, B, C), sending the results back as a message.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87) * Kernel-to-user (notifications or signals) communication is sent
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88) * over multicast groups. This allows to have multiple applications
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89) * monitoring them.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91) * Each command/signal gets assigned it's own attribute policy. This
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92) * way the validator will verify that all the attributes in there are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93) * only the ones that should be for each command/signal. Thing of an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94) * attribute mapping to a type+argumentname for each command/signal.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96) * If we had a single policy for *all* commands/signals, after running
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97) * the validator we'd have to check "does this attribute belong in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98) * here"? for each one. It can be done manually, but it's just easier
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99) * to have the validator do that job with multiple policies. As well,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) * it makes it easier to later expand each command/signal signature
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) * without affecting others and keeping the namespace more or less
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) * sane. Not that it is too complicated, but it makes it even easier.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) * No state information is maintained in the kernel for each user
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) * space connection (the connection is stateless).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) * TESTING FOR THE INTERFACE AND VERSIONING
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) * If network interface X is a WiMAX device, there will be a Generic
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) * Netlink family named "WiMAX X" and the device will present a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) * "wimax" directory in it's network sysfs directory
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) * (/sys/class/net/DEVICE/wimax) [used by HAL].
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) * The inexistence of any of these means the device does not support
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) * this WiMAX API.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) * By querying the generic netlink controller, versioning information
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) * and the multicast groups available can be found. Applications using
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) * the interface can either rely on that or use the generic netlink
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) * controller to figure out which generic netlink commands/signals are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) * supported.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) * NOTE: this versioning is a last resort to avoid hard
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) * incompatibilities. It is the intention of the design of this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) * stack not to introduce backward incompatible changes.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) * The version code has to fit in one byte (restrictions imposed by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) * generic netlink); we use `version / 10` for the major version and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) * `version % 10` for the minor. This gives 9 minors for each major
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) * and 25 majors.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) * The version change protocol is as follow:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) * - Major versions: needs to be increased if an existing message/API
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) * call is changed or removed. Doesn't need to be changed if a new
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136) * message is added.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138) * - Minor version: needs to be increased if new messages/API calls are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) * being added or some other consideration that doesn't impact the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) * user-kernel interface too much (like some kind of bug fix) and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141) * that is kind of left up in the air to common sense.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) * User space code should not try to work if the major version it was
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) * compiled for differs from what the kernel offers. As well, if the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) * minor version of the kernel interface is lower than the one user
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) * space is expecting (the one it was compiled for), the kernel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147) * might be missing API calls; user space shall be ready to handle
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148) * said condition. Use the generic netlink controller operations to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149) * find which ones are supported and which not.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151) * libwimaxll:wimaxll_open() takes care of checking versions.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153) * THE OPERATIONS:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) * Each operation is defined in its on file (drivers/net/wimax/op-*.c)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) * for clarity. The parts needed for an operation are:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158) * - a function pointer in `struct wimax_dev`: optional, as the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159) * operation might be implemented by the stack and not by the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160) * driver.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162) * All function pointers are named wimax_dev->op_*(), and drivers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163) * must implement them except where noted otherwise.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165) * - When exported to user space, a `struct nla_policy` to define the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166) * attributes of the generic netlink command and a `struct genl_ops`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167) * to define the operation.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169) * All the declarations for the operation codes (WIMAX_GNL_OP_<NAME>)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170) * and generic netlink attributes (WIMAX_GNL_<NAME>_*) are declared in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171) * include/linux/wimax.h; this file is intended to be cloned by user
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172) * space to gain access to those declarations.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174) * A few caveats to remember:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176) * - Need to define attribute numbers starting in 1; otherwise it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177) * fails.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179) * - the `struct genl_family` requires a maximum attribute id; when
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180) * defining the `struct nla_policy` for each message, it has to have
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181) * an array size of WIMAX_GNL_ATTR_MAX+1.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183) * The op_*() function pointers will not be called if the wimax_dev is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184) * in a state <= %WIMAX_ST_UNINITIALIZED. The exception is:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186) * - op_reset: can be called at any time after wimax_dev_add() has
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187) * been called.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189) * THE PIPE INTERFACE:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 191) * This interface is kept intentionally simple. The driver can send
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 192) * and receive free-form messages to/from user space through a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 193) * pipe. See drivers/net/wimax/op-msg.c for details.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 194) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 195) * The kernel-to-user messages are sent with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 196) * wimax_msg(). user-to-kernel messages are delivered via
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 197) * wimax_dev->op_msg_from_user().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 198) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 199) * RFKILL:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 200) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 201) * RFKILL support is built into the wimax_dev layer; the driver just
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 202) * needs to call wimax_report_rfkill_{hw,sw}() to inform of changes in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 203) * the hardware or software RF kill switches. When the stack wants to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 204) * turn the radio off, it will call wimax_dev->op_rfkill_sw_toggle(),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 205) * which the driver implements.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 206) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 207) * User space can set the software RF Kill switch by calling
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 208) * wimax_rfkill().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 209) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 210) * The code for now only supports devices that don't require polling;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 211) * If the device needs to be polled, create a self-rearming delayed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 212) * work struct for polling or look into adding polled support to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 213) * WiMAX stack.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 214) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 215) * When initializing the hardware (_probe), after calling
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 216) * wimax_dev_add(), query the device for it's RF Kill switches status
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 217) * and feed it back to the WiMAX stack using
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 218) * wimax_report_rfkill_{hw,sw}(). If any switch is missing, always
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 219) * report it as ON.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 220) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 221) * NOTE: the wimax stack uses an inverted terminology to that of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 222) * RFKILL subsystem:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 223) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 224) * - ON: radio is ON, RFKILL is DISABLED or OFF.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 225) * - OFF: radio is OFF, RFKILL is ENABLED or ON.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 226) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 227) * MISCELLANEOUS OPS:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 228) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 229) * wimax_reset() can be used to reset the device to power on state; by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 230) * default it issues a warm reset that maintains the same device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 231) * node. If that is not possible, it falls back to a cold reset
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 232) * (device reconnect). The driver implements the backend to this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 233) * through wimax_dev->op_reset().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 234) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 235)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 236) #ifndef __NET__WIMAX_H__
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 237) #define __NET__WIMAX_H__
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 238)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 239) #include <linux/wimax.h>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 240) #include <net/genetlink.h>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 241) #include <linux/netdevice.h>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 242)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 243) struct net_device;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 244) struct genl_info;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 245) struct wimax_dev;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 246)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 247) /**
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 248) * struct wimax_dev - Generic WiMAX device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 249) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 250) * @net_dev: [fill] Pointer to the &struct net_device this WiMAX
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 251) * device implements.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 252) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 253) * @op_msg_from_user: [fill] Driver-specific operation to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 254) * handle a raw message from user space to the driver. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 255) * driver can send messages to user space using with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 256) * wimax_msg_to_user().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 257) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 258) * @op_rfkill_sw_toggle: [fill] Driver-specific operation to act on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 259) * userspace (or any other agent) requesting the WiMAX device to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 260) * change the RF Kill software switch (WIMAX_RF_ON or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 261) * WIMAX_RF_OFF).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 262) * If such hardware support is not present, it is assumed the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 263) * radio cannot be switched off and it is always on (and the stack
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 264) * will error out when trying to switch it off). In such case,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 265) * this function pointer can be left as NULL.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 266) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 267) * @op_reset: [fill] Driver specific operation to reset the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 268) * device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 269) * This operation should always attempt first a warm reset that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 270) * does not disconnect the device from the bus and return 0.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 271) * If that fails, it should resort to some sort of cold or bus
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 272) * reset (even if it implies a bus disconnection and device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 273) * disappearance). In that case, -ENODEV should be returned to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 274) * indicate the device is gone.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 275) * This operation has to be synchronous, and return only when the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 276) * reset is complete. In case of having had to resort to bus/cold
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 277) * reset implying a device disconnection, the call is allowed to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 278) * return immediately.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 279) * NOTE: wimax_dev->mutex is NOT locked when this op is being
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 280) * called; however, wimax_dev->mutex_reset IS locked to ensure
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 281) * serialization of calls to wimax_reset().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 282) * See wimax_reset()'s documentation.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 283) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 284) * @name: [fill] A way to identify this device. We need to register a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 285) * name with many subsystems (rfkill, workqueue creation, etc).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 286) * We can't use the network device name as that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 287) * might change and in some instances we don't know it yet (until
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 288) * we don't call register_netdev()). So we generate an unique one
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 289) * using the driver name and device bus id, place it here and use
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 290) * it across the board. Recommended naming:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 291) * DRIVERNAME-BUSNAME:BUSID (dev->bus->name, dev->bus_id).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 292) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 293) * @id_table_node: [private] link to the list of wimax devices kept by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 294) * id-table.c. Protected by it's own spinlock.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 295) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 296) * @mutex: [private] Serializes all concurrent access and execution of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 297) * operations.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 298) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 299) * @mutex_reset: [private] Serializes reset operations. Needs to be a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 300) * different mutex because as part of the reset operation, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 301) * driver has to call back into the stack to do things such as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 302) * state change, that require wimax_dev->mutex.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 303) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 304) * @state: [private] Current state of the WiMAX device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 305) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 306) * @rfkill: [private] integration into the RF-Kill infrastructure.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 307) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 308) * @rf_sw: [private] State of the software radio switch (OFF/ON)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 309) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 310) * @rf_hw: [private] State of the hardware radio switch (OFF/ON)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 311) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 312) * @debugfs_dentry: [private] Used to hook up a debugfs entry. This
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 313) * shows up in the debugfs root as wimax\:DEVICENAME.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 314) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 315) * Description:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 316) * This structure defines a common interface to access all WiMAX
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 317) * devices from different vendors and provides a common API as well as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 318) * a free-form device-specific messaging channel.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 319) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 320) * Usage:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 321) * 1. Embed a &struct wimax_dev at *the beginning* the network
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 322) * device structure so that netdev_priv() points to it.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 323) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 324) * 2. memset() it to zero
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 325) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 326) * 3. Initialize with wimax_dev_init(). This will leave the WiMAX
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 327) * device in the %__WIMAX_ST_NULL state.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 328) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 329) * 4. Fill all the fields marked with [fill]; once called
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 330) * wimax_dev_add(), those fields CANNOT be modified.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 331) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 332) * 5. Call wimax_dev_add() *after* registering the network
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 333) * device. This will leave the WiMAX device in the %WIMAX_ST_DOWN
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 334) * state.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 335) * Protect the driver's net_device->open() against succeeding if
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 336) * the wimax device state is lower than %WIMAX_ST_DOWN.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 337) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 338) * 6. Select when the device is going to be turned on/initialized;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 339) * for example, it could be initialized on 'ifconfig up' (when the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 340) * netdev op 'open()' is called on the driver).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 341) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 342) * When the device is initialized (at `ifconfig up` time, or right
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 343) * after calling wimax_dev_add() from _probe(), make sure the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 344) * following steps are taken
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 345) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 346) * a. Move the device to %WIMAX_ST_UNINITIALIZED. This is needed so
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 347) * some API calls that shouldn't work until the device is ready
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 348) * can be blocked.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 349) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 350) * b. Initialize the device. Make sure to turn the SW radio switch
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 351) * off and move the device to state %WIMAX_ST_RADIO_OFF when
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 352) * done. When just initialized, a device should be left in RADIO
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 353) * OFF state until user space devices to turn it on.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 354) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 355) * c. Query the device for the state of the hardware rfkill switch
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 356) * and call wimax_rfkill_report_hw() and wimax_rfkill_report_sw()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 357) * as needed. See below.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 358) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 359) * wimax_dev_rm() undoes before unregistering the network device. Once
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 360) * wimax_dev_add() is called, the driver can get called on the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 361) * wimax_dev->op_* function pointers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 362) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 363) * CONCURRENCY:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 364) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 365) * The stack provides a mutex for each device that will disallow API
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 366) * calls happening concurrently; thus, op calls into the driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 367) * through the wimax_dev->op*() function pointers will always be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 368) * serialized and *never* concurrent.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 369) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 370) * For locking, take wimax_dev->mutex is taken; (most) operations in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 371) * the API have to check for wimax_dev_is_ready() to return 0 before
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 372) * continuing (this is done internally).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 373) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 374) * REFERENCE COUNTING:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 375) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 376) * The WiMAX device is reference counted by the associated network
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 377) * device. The only operation that can be used to reference the device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 378) * is wimax_dev_get_by_genl_info(), and the reference it acquires has
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 379) * to be released with dev_put(wimax_dev->net_dev).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 380) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 381) * RFKILL:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 382) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 383) * At startup, both HW and SW radio switchess are assumed to be off.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 384) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 385) * At initialization time [after calling wimax_dev_add()], have the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 386) * driver query the device for the status of the software and hardware
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 387) * RF kill switches and call wimax_report_rfkill_hw() and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 388) * wimax_rfkill_report_sw() to indicate their state. If any is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 389) * missing, just call it to indicate it is ON (radio always on).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 390) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 391) * Whenever the driver detects a change in the state of the RF kill
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 392) * switches, it should call wimax_report_rfkill_hw() or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 393) * wimax_report_rfkill_sw() to report it to the stack.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 394) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 395) struct wimax_dev {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 396) struct net_device *net_dev;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 397) struct list_head id_table_node;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 398) struct mutex mutex; /* Protects all members and API calls */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 399) struct mutex mutex_reset;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 400) enum wimax_st state;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 401)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 402) int (*op_msg_from_user)(struct wimax_dev *wimax_dev,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 403) const char *,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 404) const void *, size_t,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 405) const struct genl_info *info);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 406) int (*op_rfkill_sw_toggle)(struct wimax_dev *wimax_dev,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 407) enum wimax_rf_state);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 408) int (*op_reset)(struct wimax_dev *wimax_dev);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 409)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 410) struct rfkill *rfkill;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 411) unsigned int rf_hw;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 412) unsigned int rf_sw;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 413) char name[32];
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 414)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 415) struct dentry *debugfs_dentry;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 416) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 417)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 418)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 419)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 420) /*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 421) * WiMAX stack public API for device drivers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 422) * -----------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 423) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 424) * These functions are not exported to user space.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 425) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 426) void wimax_dev_init(struct wimax_dev *);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 427) int wimax_dev_add(struct wimax_dev *, struct net_device *);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 428) void wimax_dev_rm(struct wimax_dev *);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 429)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 430) static inline
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 431) struct wimax_dev *net_dev_to_wimax(struct net_device *net_dev)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 432) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 433) return netdev_priv(net_dev);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 434) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 435)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 436) static inline
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 437) struct device *wimax_dev_to_dev(struct wimax_dev *wimax_dev)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 438) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 439) return wimax_dev->net_dev->dev.parent;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 440) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 441)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 442) void wimax_state_change(struct wimax_dev *, enum wimax_st);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 443) enum wimax_st wimax_state_get(struct wimax_dev *);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 444)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 445) /*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 446) * Radio Switch state reporting.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 447) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 448) * enum wimax_rf_state is declared in linux/wimax.h so the exports
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 449) * to user space can use it.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 450) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 451) void wimax_report_rfkill_hw(struct wimax_dev *, enum wimax_rf_state);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 452) void wimax_report_rfkill_sw(struct wimax_dev *, enum wimax_rf_state);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 453)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 454)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 455) /*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 456) * Free-form messaging to/from user space
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 457) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 458) * Sending a message:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 459) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 460) * wimax_msg(wimax_dev, pipe_name, buf, buf_size, GFP_KERNEL);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 461) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 462) * Broken up:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 463) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 464) * skb = wimax_msg_alloc(wimax_dev, pipe_name, buf_size, GFP_KERNEL);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 465) * ...fill up skb...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 466) * wimax_msg_send(wimax_dev, pipe_name, skb);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 467) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 468) * Be sure not to modify skb->data in the middle (ie: don't use
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 469) * skb_push()/skb_pull()/skb_reserve() on the skb).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 470) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 471) * "pipe_name" is any string, that can be interpreted as the name of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 472) * the pipe or recipient; the interpretation of it is driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 473) * specific, so the recipient can multiplex it as wished. It can be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 474) * NULL, it won't be used - an example is using a "diagnostics" tag to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 475) * send diagnostics information that a device-specific diagnostics
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 476) * tool would be interested in.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 477) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 478) struct sk_buff *wimax_msg_alloc(struct wimax_dev *, const char *, const void *,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 479) size_t, gfp_t);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 480) int wimax_msg_send(struct wimax_dev *, struct sk_buff *);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 481) int wimax_msg(struct wimax_dev *, const char *, const void *, size_t, gfp_t);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 482)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 483) const void *wimax_msg_data_len(struct sk_buff *, size_t *);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 484) const void *wimax_msg_data(struct sk_buff *);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 485) ssize_t wimax_msg_len(struct sk_buff *);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 486)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 487)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 488) /*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 489) * WiMAX stack user space API
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 490) * --------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 491) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 492) * This API is what gets exported to user space for general
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 493) * operations. As well, they can be called from within the kernel,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 494) * (with a properly referenced `struct wimax_dev`).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 495) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 496) * Properly referenced means: the 'struct net_device' that embeds the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 497) * device's control structure and (as such) the 'struct wimax_dev' is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 498) * referenced by the caller.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 499) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 500) int wimax_rfkill(struct wimax_dev *, enum wimax_rf_state);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 501) int wimax_reset(struct wimax_dev *);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 502)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 503) #endif /* #ifndef __NET__WIMAX_H__ */
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags