Skip to content

Commit

Permalink
Add more nullability annotations (#68)
Browse files Browse the repository at this point in the history
* add more nullability annotations

* more annotations

* more annotations

* random newline

* remove padding vars; update doc link
  • Loading branch information
bgiori authored Feb 24, 2020
1 parent a7b88e7 commit 32fdbe4
Show file tree
Hide file tree
Showing 21 changed files with 117 additions and 69 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -288,7 +288,7 @@ public <T extends McuMgrResponse> T send(@NotNull byte[] data, @NotNull Class<T>
* @throws McuMgrException if the payload map could not be serialized into CBOR. See cause.
*/
@NotNull
public static byte[] buildPacket(McuMgrScheme scheme, int op, int flags, int groupId,
public static byte[] buildPacket(@NotNull McuMgrScheme scheme, int op, int flags, int groupId,
int sequenceNum, int commandId,
@Nullable Map<String, Object> payloadMap)
throws McuMgrException {
Expand Down
21 changes: 17 additions & 4 deletions mcumgr-core/src/main/java/io/runtime/mcumgr/McuMgrHeader.java
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@
*/
@SuppressWarnings({"unused", "WeakerAccess"})
public class McuMgrHeader {

public final static int HEADER_LENGTH = 8;

private int mOp;
Expand All @@ -38,6 +39,7 @@ public McuMgrHeader(int op, int flags, int len, int groupId, int sequenceNum, in
mCommandId = commandId;
}

@NotNull
public byte[] toBytes() {
return build(mOp, mFlags, mLen, mGroupId, mSequenceNum, mCommandId);
}
Expand Down Expand Up @@ -90,14 +92,25 @@ public void setCommandId(int commandId) {
this.mCommandId = commandId;
}

@NotNull
@Override
public String toString() {
return "Header (Op: " + mOp + ", Flags: " + mFlags + ", Len: " + mLen + ", Group: " + mGroupId + ", Seq: " + mSequenceNum + ", Command: " + mCommandId + ")";
return "Header (Op: " + mOp + ", Flags: " + mFlags + ", Len: " + mLen + ", Group: " +
mGroupId + ", Seq: " + mSequenceNum + ", Command: " + mCommandId + ")";
}

public static McuMgrHeader fromBytes(byte[] header) {
if (header == null || header.length != HEADER_LENGTH) {
return null;
/**
* Parse the mcumgr header from a byte array.
* This function will parse the first 8 bytes from the array, discounting any additional bytes.
*
* @param header the byte array to parse the header from.
* @return The parsed mcumgr header.
* @throws IllegalArgumentException when the byte array length is less than 8 bytes
*/
@NotNull
public static McuMgrHeader fromBytes(@NotNull byte[] header) {
if (header.length < HEADER_LENGTH) {
throw new IllegalArgumentException("Failed to parse mcumgr header from bytes; too short - length=" + header.length);
}
int op = ByteUtil.byteArrayToUnsignedInt(header, 0, Endian.BIG, 1);
int flags = ByteUtil.byteArrayToUnsignedInt(header, 1, Endian.BIG, 1);
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,7 @@ public CoreDumpHeader(int magic, int size) {
* @return The core dump header.
* @throws IOException If the magic number was invalid.
*/
@NotNull
public static CoreDumpHeader fromBytes(@NotNull byte[] data) throws IOException {
return fromBytes(data, OFFSET);
}
Expand All @@ -41,6 +42,7 @@ public static CoreDumpHeader fromBytes(@NotNull byte[] data) throws IOException
* @return The core dump header.
* @throws IOException If the magic number was invalid.
*/
@NotNull
public static CoreDumpHeader fromBytes(@NotNull byte[] data, int offset) throws IOException {
int magic = ByteUtil.byteArrayToUnsignedInt(data, offset, Endian.LITTLE, 4);
if (magic != CoreDump.MAGIC) {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@ public class CoreDumpTlv {

private static final int OFFSET = 8;

@NotNull
private List<CoreDumpTlvEntry> mEntries;

public CoreDumpTlv(@NotNull List<CoreDumpTlvEntry> entries) {
Expand Down Expand Up @@ -81,6 +82,11 @@ public List<CoreDumpTlvEntry> getEntriesOfType(int type) {
return entries;
}

/**
* Get the list of core dump TLV entries.
* @return the list of TLV entries
*/
@NotNull
public List<CoreDumpTlvEntry> getEntries() {
return mEntries;
}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,6 @@ public class CoreDumpTlvEntry {
private static final int MIN_SIZE = 8;

private int mType; // uint8_t
//private byte __pad; // uint8_t
private int mLength; // uint16_t
private long mOff; // uint32_t

Expand Down Expand Up @@ -77,6 +76,7 @@ public static CoreDumpTlvEntry fromBytes(@NotNull byte[] data, int offset) throw
return new CoreDumpTlvEntry(type, length, off, value);
}

@NotNull
@Override
public String toString() {
return String.format("{type=%s, length=%s, off=%s, value=%s}", mType, mLength, mOff,
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@
* image header and type-length-value trailer for image meta-data.
* <p>
* For more info about McuBoot and image format see:
* <a href="https://runtimeco.github.io/mcuboot/design.html">https://runtimeco.github.io/mcuboot/design.html</a>
* <a href="https://juullabs-oss.github.io/mcuboot/design.html">https://juullabs-oss.github.io/mcuboot/design.html</a>
*/
@SuppressWarnings({"WeakerAccess", "unused"})
public class McuMgrImage {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -18,50 +18,62 @@
* bootloader.
* <p>
* For more info about McuBoot and image format see:
* <a href="https://runtimeco.github.io/mcuboot/design.html">https://runtimeco.github.io/mcuboot/design.html</a>
* <a href="https://juullabs-oss.github.io/mcuboot/design.html">https://juullabs-oss.github.io/mcuboot/design.html</a>
*/
@SuppressWarnings({"unused", "WeakerAccess"})
public class McuMgrImageHeader {

private static final int IMG_HEADER_MAGIC = 0x96f3b83d;
private static final int IMG_HEADER_MAGIC_V1 = 0x96f3b83c;

private static final int HEADER_LENGTH = 4 + 4 + 2 + 2 + 4 + 4 + 4;
private static final int HEADER_LENGTH = 24;
private int mMagic;
private int mLoadAddr;
private short mHdrSize;
private short __mPad1;
private int mImgSize;
private int mFlags;
@NotNull
private McuMgrImageVersion mVersion;
private int __mPad2;

private McuMgrImageHeader() {}
private McuMgrImageHeader(int magic,
int loadAddr,
short hdrSize,
int imgSize,
int flags,
@NotNull McuMgrImageVersion version) {
mMagic = magic;
mLoadAddr = loadAddr;
mHdrSize = hdrSize;
mImgSize = imgSize;
mFlags = flags;
mVersion = version;
}

@NotNull
public static McuMgrImageHeader fromBytes(@NotNull byte[] b) throws McuMgrException {
return fromBytes(b, 0);
}

@NotNull
public static McuMgrImageHeader fromBytes(@NotNull byte[] b, int offset) throws McuMgrException {
if (b.length - offset < getSize()) {
throw new McuMgrException("The byte array is too short to be a McuMgrImageHeader");
}

McuMgrImageHeader header = new McuMgrImageHeader();
header.mMagic = ByteUtil.byteArrayToUnsignedInt(b, offset, Endian.LITTLE, 4);
int magic = ByteUtil.byteArrayToUnsignedInt(b, offset, Endian.LITTLE, 4);

if (header.mMagic != IMG_HEADER_MAGIC && header.mMagic != IMG_HEADER_MAGIC_V1) {
throw new McuMgrException("Wrong magic number: header=" + header.mMagic + ", magic=" +
if (magic != IMG_HEADER_MAGIC && magic != IMG_HEADER_MAGIC_V1) {
throw new McuMgrException("Wrong magic number: header=" + magic + ", magic=" +
IMG_HEADER_MAGIC + " or " + IMG_HEADER_MAGIC_V1);
}

header.mLoadAddr = ByteUtil.byteArrayToUnsignedInt(b, 4 + offset, Endian.LITTLE, 4);
header.mHdrSize = (short) ByteUtil.byteArrayToUnsignedInt(b, 8 + offset, Endian.LITTLE, 2);
header.mImgSize = ByteUtil.byteArrayToUnsignedInt(b, 12 + offset, Endian.LITTLE, 4);
header.mFlags = ByteUtil.byteArrayToUnsignedInt(b, 16 + offset, Endian.LITTLE, 4);
header.mVersion = McuMgrImageVersion.fromBytes(b, 20 + offset);
int loadAddr = ByteUtil.byteArrayToUnsignedInt(b, 4 + offset, Endian.LITTLE, 4);
short hdrSize = (short) ByteUtil.byteArrayToUnsignedInt(b, 8 + offset, Endian.LITTLE, 2);
int imgSize = ByteUtil.byteArrayToUnsignedInt(b, 12 + offset, Endian.LITTLE, 4);
int flags = ByteUtil.byteArrayToUnsignedInt(b, 16 + offset, Endian.LITTLE, 4);
McuMgrImageVersion version = McuMgrImageVersion.fromBytes(b, 20 + offset);

return header;
return new McuMgrImageHeader(magic, loadAddr, hdrSize, imgSize, flags, version);
}

public static int getSize() {
Expand All @@ -88,6 +100,7 @@ public int getFlags() {
return mFlags;
}

@NotNull
public McuMgrImageVersion getVersion() {
return mVersion;
}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,8 @@

package io.runtime.mcumgr.image;

import org.jetbrains.annotations.NotNull;

import io.runtime.mcumgr.exception.McuMgrException;
import io.runtime.mcumgr.util.ByteUtil;
import io.runtime.mcumgr.util.Endian;
Expand All @@ -15,33 +17,40 @@
* bootloader.
* <p>
* For more info about McuBoot and image format see:
* <a href="https://runtimeco.github.io/mcuboot/design.html">https://runtimeco.github.io/mcuboot/design.html</a>
* <a href="https://juullabs-oss.github.io/mcuboot/design.html">https://juullabs-oss.github.io/mcuboot/design.html</a>
*/
@SuppressWarnings("unused")
public class McuMgrImageVersion {

private byte mMajor;
private byte mMinor;
private short mRevision;
private int mBuildNum;

private McuMgrImageVersion() {}
private McuMgrImageVersion(byte major, byte minor, short revision, int buildNum) {
mMajor = major;
mMinor = minor;
mRevision = revision;
mBuildNum = buildNum;
}

public static McuMgrImageVersion fromBytes(byte[] b) throws McuMgrException {
@NotNull
public static McuMgrImageVersion fromBytes(@NotNull byte[] b) throws McuMgrException {
return fromBytes(b, 0);
}

public static McuMgrImageVersion fromBytes(byte[] b, int offset) throws McuMgrException {
@NotNull
public static McuMgrImageVersion fromBytes(@NotNull byte[] b, int offset) throws McuMgrException {
if (b.length - offset < getSize()) {
throw new McuMgrException("The byte array is too short to be a McuMgrImageVersion");
}

McuMgrImageVersion version = new McuMgrImageVersion();
version.mMajor = b[offset++];
version.mMinor = b[offset++];
version.mRevision = (short) ByteUtil.byteArrayToUnsignedInt(b, offset, Endian.LITTLE, 2);
version.mBuildNum = ByteUtil.byteArrayToUnsignedInt(b, offset + 2, Endian.LITTLE, 4);
byte major = b[offset++];
byte minor = b[offset++];
short revision = (short) ByteUtil.byteArrayToUnsignedInt(b, offset, Endian.LITTLE, 2);
int buildNum = ByteUtil.byteArrayToUnsignedInt(b, offset + 2, Endian.LITTLE, 4);

return version;
return new McuMgrImageVersion(major, minor, revision, buildNum);
}

public static int getSize() {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@
* Mynewt bootloader.
* <p>
* For more info about McuBoot and image format see:
* <a href="https://runtimeco.github.io/mcuboot/design.html">https://runtimeco.github.io/mcuboot/design.html</a>
* <a href="https://juullabs-oss.github.io/mcuboot/design.html">https://juullabs-oss.github.io/mcuboot/design.html</a>
*/
@SuppressWarnings({"unused", "WeakerAccess"})
public class McuMgrImageTlv {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@
* Mynewt bootloader.
* <p>
* For more info about McuBoot and image format see:
* <a href="https://runtimeco.github.io/mcuboot/design.html">https://runtimeco.github.io/mcuboot/design.html</a>
* <a href="https://juullabs-oss.github.io/mcuboot/design.html">https://juullabs-oss.github.io/mcuboot/design.html</a>
*/
@SuppressWarnings("unused")
public class McuMgrImageTlvInfo {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@
* Apache Mynewt bootloader.
* <p>
* For more info about McuBoot and image format see:
* <a href="https://runtimeco.github.io/mcuboot/design.html">https://runtimeco.github.io/mcuboot/design.html</a>
* <a href="https://juullabs-oss.github.io/mcuboot/design.html">https://juullabs-oss.github.io/mcuboot/design.html</a>
*/
public class McuMgrImageTlvTrailerEntry {
public final byte type;
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,7 @@ public CrashManager(@NotNull McuMgrTransport transporter) {
* @return The response
* @throws McuMgrException on failure.
*/
@NotNull
public McuMgrResponse test(@NotNull Test test) throws McuMgrException {
HashMap<String, Object> payloadMap = new HashMap<>();
payloadMap.put("t", test.toString());
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -135,6 +135,7 @@ public McuMgrFsUploadResponse upload(@NotNull String name, @NotNull byte[] data,
/*
* Build the upload payload map.
*/
@NotNull
private HashMap<String, Object> buildUploadPayload(@NotNull String name, @NotNull byte[] data, int offset) {
// Get the length of data (in bytes) to put into the upload packet. This calculated as:
// min(MTU - packetOverhead, imageLength - uploadOffset)
Expand Down Expand Up @@ -175,6 +176,7 @@ private HashMap<String, Object> buildUploadPayload(@NotNull String name, @NotNul
* @return The object used to control this upload.
* @see TransferController
*/
@NotNull
public TransferController fileUpload(@NotNull String name, @NotNull byte[] data, @NotNull UploadCallback callback) {
return startUpload(new FileUpload(name, data, callback));
}
Expand Down Expand Up @@ -215,6 +217,7 @@ protected UploadResponse write(@NotNull byte[] data, int offset) throws McuMgrEx
* @return The object used to control this upload.
* @see TransferController
*/
@NotNull
public TransferController fileDownload(@NotNull String name, @NotNull byte[] data, @NotNull DownloadCallback callback) {
return startDownload(new FileDownload(name, callback));
}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -149,6 +149,7 @@ public McuMgrImageUploadResponse upload(@NotNull byte[] data, int offset) throws
/*
* Build the upload payload.
*/
@NotNull
private HashMap<String, Object> buildUploadPayload(@NotNull byte[] data, int offset) {
// Get chunk of image data to send
int dataLength = Math.min(mMtu - calculatePacketOverhead(data, offset), data.length - offset);
Expand Down Expand Up @@ -387,6 +388,7 @@ public McuMgrResponse coreErase() throws McuMgrException {
* @see TransferController
* @see CoreDump
*/
@NotNull
public TransferController coreDownload(@NotNull DownloadCallback callback) {
return startDownload(new CoreDownload(callback));
}
Expand Down Expand Up @@ -422,6 +424,7 @@ public DownloadResponse read(int offset) throws McuMgrException {
* @return The object used to control this upload.
* @see TransferController
*/
@NotNull
public TransferController imageUpload(@NotNull byte[] imageData, @NotNull UploadCallback callback) {
return startUpload(new ImageUpload(imageData, callback));
}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -127,7 +127,6 @@ public McuMgrLogResponse show(@Nullable String logName, @Nullable Long minIndex,
return send(OP_READ, ID_READ, payloadMap, McuMgrLogResponse.class);
}


/**
* Clear the logs on a device (asynchronous).
*
Expand Down Expand Up @@ -221,6 +220,7 @@ public McuMgrLogListResponse logsList() throws McuMgrException {
*
* @return A mapping of log name to state.
*/
@NotNull
public synchronized Map<String, State> getAll() {
HashMap<String, State> logStates = new HashMap<>();
try {
Expand Down Expand Up @@ -259,10 +259,8 @@ public synchronized Map<String, State> getAll() {
* @param state The log state to collect logs from.
* @return The log state with updated next index and entry list.
*/
public State getAllFromState(State state) {
if (state == null) {
throw new NullPointerException("State must not be null!");
}
@NotNull
public State getAllFromState(@NotNull State state) {
// Loop until we run out of entries or encounter a problem
while (true) {
// Get the next set of entries for this log
Expand Down Expand Up @@ -309,7 +307,8 @@ public State getAllFromState(State state) {
* @param state The state to get logs from.
* @return The show response.
*/
public McuMgrLogResponse showNext(State state) {
@Nullable
public McuMgrLogResponse showNext(@NotNull State state) {
LOG.debug("Show logs: name={}, nextIndex={}", state.getName(), state.getNextIndex());
try {
McuMgrLogResponse response = show(state.getName(), state.getNextIndex(), null);
Expand Down
Loading

0 comments on commit 32fdbe4

Please sign in to comment.