system/ulib/ddk/include/ddk/protocol/ethernet.h

// Copyright 2018 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

// WARNING: This file is machine generated by fidlc.

#pragma once

#include <zircon/compiler.h>
#include <zircon/listnode.h>
#include <zircon/types.h>

__BEGIN_CDECLS;

// Forward declarations

typedef union internal internal_t;
// The ethermac interface supports both synchronous and asynchronous transmissions using the
// proto->queue_tx() and ifc->complete_tx() methods.
// Receive operations are supported with the ifc->recv() interface.
// The FEATURE_WLAN flag indicates a device that supports wlan operations.
// The FEATURE_SYNTH flag indicates a device that is not backed by hardware.
// The FEATURE_DMA flag indicates that the device can copy the buffer data using DMA and will ensure
// that physical addresses are provided in netbufs.
typedef uint32_t ethmac_feature_t;
#define ETHMAC_FEATURE_WLAN UINT32_C(1)
#define ETHMAC_FEATURE_SYNTH UINT32_C(2)
#define ETHMAC_FEATURE_DMA UINT32_C(4)

typedef struct ethmac_info ethmac_info_t;
typedef struct ethmac_netbuf ethmac_netbuf_t;
typedef struct ethmac_ifc ethmac_ifc_t;
typedef struct ethmac_protocol ethmac_protocol_t;

// Declarations

union internal {
    uint64_t val;
    void* ptr_buffer;
    size_t ptr_size;
};

#define ETHMAC_SETPARAM_DUMP_REGS UINT32_C(4)

// |value| is number of addresses, or ETHMAC_MULTICAST_FILTER_OVERFLOW for "too many to count."
// |data| is |value|*6 bytes of MAC addresses. Caller retains ownership.
// If |value| is _OVERFLOW, |data| is ignored.
#define ETHMAC_SETPARAM_MULTICAST_FILTER UINT32_C(3)

#define ETHMAC_MULTICAST_FILTER_OVERFLOW INT32_C(-1)

// |value| is bool. |data| is unused.
#define ETHMAC_SETPARAM_MULTICAST_PROMISC UINT32_C(2)

// Indicates that additional data is available to be sent after this call finishes. Allows a ethmac
// driver to batch tx to hardware if possible.
#define ETHMAC_TX_OPT_MORE UINT32_C(1)

struct ethmac_info {
    uint32_t features;
    uint32_t mtu;
    uint8_t mac[6];
    uint8_t reserved0[2];
    uint32_t reserved1[4];
};

// SETPARAM_ values identify the parameter to set. Each call to set_param()
// takes an int32_t |value| and void* |data| which have meaning specific to
// the parameter being set.
// |value| is bool. |data| is unused.
#define ETHMAC_SETPARAM_PROMISC UINT32_C(1)

#define ETH_FRAME_MAX_SIZE UINT32_C(1518)

#define ETH_FRAME_MAX_HDR_SIZE UINT32_C(18)

#define ETH_MTU_SIZE UINT32_C(1500)

#define ETH_MAC_SIZE UINT32_C(6)

struct ethmac_netbuf {
    // Provided by the generic ethernet driver.
    void* data_buffer;
    size_t data_size;
    // Only used if ETHMAC_FEATURE_DMA is available.
    uint64_t phys;
    uint16_t reserved;
    uint32_t flags;
    // Shared between the generic ethernet and ethmac drivers.
    list_node_t node;
    // For use by the ethmac driver.
    internal_t u;
};

typedef struct ethmac_ifc_ops {
    void (*status)(void* ctx, uint32_t status);
    void (*recv)(void* ctx, const void* data_buffer, size_t data_size, uint32_t flags);
    void (*complete_tx)(void* ctx, ethmac_netbuf_t* netbuf, zx_status_t status);
} ethmac_ifc_ops_t;

struct ethmac_ifc {
    ethmac_ifc_ops_t* ops;
    void* ctx;
};

static inline void ethmac_ifc_status(const ethmac_ifc_t* proto, uint32_t status) {
    proto->ops->status(proto->ctx, status);
}
static inline void ethmac_ifc_recv(const ethmac_ifc_t* proto, const void* data_buffer,
                                   size_t data_size, uint32_t flags) {
    proto->ops->recv(proto->ctx, data_buffer, data_size, flags);
}
// complete_tx() is called to return ownership of a netbuf to the generic ethernet driver.
// Return status indicates queue state:
//   ZX_OK: Packet has been enqueued.
//   Other: Packet could not be enqueued.
// Upon a return of ZX_OK, the packet has been enqueued, but no information is returned as to
// the completion state of the transmission itself.
static inline void ethmac_ifc_complete_tx(const ethmac_ifc_t* proto, ethmac_netbuf_t* netbuf,
                                          zx_status_t status) {
    proto->ops->complete_tx(proto->ctx, netbuf, status);
}

typedef struct ethmac_protocol_ops {
    zx_status_t (*query)(void* ctx, uint32_t options, ethmac_info_t* out_info);
    void (*stop)(void* ctx);
    zx_status_t (*start)(void* ctx, const ethmac_ifc_t* ifc);
    zx_status_t (*queue_tx)(void* ctx, uint32_t options, ethmac_netbuf_t* netbuf);
    zx_status_t (*set_param)(void* ctx, uint32_t param, zx_status_t value, const void* data_buffer,
                             size_t data_size);
    zx_handle_t (*get_bti)(void* ctx);
} ethmac_protocol_ops_t;

// The ethernet midlayer will never call ethermac_protocol
// methods from multiple threads simultaneously, but it
// can call send() methods at the same time as non-send
// methods.
struct ethmac_protocol {
    ethmac_protocol_ops_t* ops;
    void* ctx;
};

// Obtain information about the ethermac device and supported features
// Safe to call at any time.
static inline zx_status_t ethmac_query(const ethmac_protocol_t* proto, uint32_t options,
                                       ethmac_info_t* out_info) {
    return proto->ops->query(proto->ctx, options, out_info);
}
// Shut down a running ethermac
// Safe to call if the ethermac is already stopped.
static inline void ethmac_stop(const ethmac_protocol_t* proto) {
    proto->ops->stop(proto->ctx);
}
// Start ethermac running with ifc_virt
// Callbacks on ifc may be invoked from now until stop() is called
static inline zx_status_t ethmac_start(const ethmac_protocol_t* proto, const ethmac_ifc_t* ifc) {
    return proto->ops->start(proto->ctx, ifc);
}
// Request transmission of the packet in netbuf. Return status indicates queue state:
//   ZX_ERR_SHOULD_WAIT: Packet is being enqueued.
//   ZX_OK: Packet has been enqueued.
//   Other: Packet could not be enqueued.
// In the SHOULD_WAIT case the driver takes ownership of the netbuf and must call complete_tx()
// to return it once the enqueue is complete. complete_tx() may be used to return the packet
// before transmission itself completes, but MUST NOT be called from within the queue_tx()
// implementation.
// queue_tx() may be called at any time after start() is called including from multiple threads
// simultaneously.
static inline zx_status_t ethmac_queue_tx(const ethmac_protocol_t* proto, uint32_t options,
                                          ethmac_netbuf_t* netbuf) {
    return proto->ops->queue_tx(proto->ctx, options, netbuf);
}
// Request a settings change for the driver. Return status indicates disposition:
//   ZX_OK: Request has been handled.
//   ZX_ERR_NOT_SUPPORTED: Driver does not support this setting.
//   Other: Error trying to support this request.
// |value| and |data| usage are defined for each |param|; see comments above.
// set_param() may be called at any time after start() is called including from multiple threads
// simultaneously.
static inline zx_status_t ethmac_set_param(const ethmac_protocol_t* proto, uint32_t param,
                                           zx_status_t value, const void* data_buffer,
                                           size_t data_size) {
    return proto->ops->set_param(proto->ctx, param, value, data_buffer, data_size);
}
// Get the BTI handle (needed to pin DMA memory) for this device.
// This method is only valid on devices that advertise ETHMAC_FEATURE_DMA
// The caller does *not* take ownership of the BTI handle and must never close
// the handle.
static inline zx_handle_t ethmac_get_bti(const ethmac_protocol_t* proto) {
    return proto->ops->get_bti(proto->ctx);
}

__END_CDECLS;